@monque/core 0.3.0 → 1.1.0

package/dist/index.cjs

@@ -1,7 +1,7 @@
-const require_errors = require('./errors-D5ZGG2uI.cjs');
+let mongodb = require("mongodb");
+let cron_parser = require("cron-parser");
 let node_crypto = require("node:crypto");
 let node_events = require("node:events");
-let cron_parser = require("cron-parser");
 
 //#region src/jobs/types.ts
 /**
@@ -12,6 +12,7 @@ let cron_parser = require("cron-parser");
 * - PROCESSING → COMPLETED (on success)
 * - PROCESSING → PENDING (on failure, if retries remain)
 * - PROCESSING → FAILED (on failure, after max retries exhausted)
+* - PENDING → CANCELLED (on manual cancellation)
 *
 * @example
 * ```typescript
@@ -24,7 +25,20 @@ const JobStatus = {
 	PENDING: "pending",
 	PROCESSING: "processing",
 	COMPLETED: "completed",
-	FAILED: "failed"
+	FAILED: "failed",
+	CANCELLED: "cancelled"
+};
+/**
+* Valid cursor directions for pagination.
+*
+* @example
+* ```typescript
+* const direction = CursorDirection.FORWARD;
+* ```
+*/
+const CursorDirection = {
+	FORWARD: "forward",
+	BACKWARD: "backward"
 };
 
 //#endregion
@@ -68,8 +82,8 @@ function isPersistedJob(job) {
 /**
 * Type guard to check if a value is a valid job status.
 *
-* Validates that a value is one of the four valid job statuses: `'pending'`,
-* `'processing'`, `'completed'`, or `'failed'`. Useful for runtime validation
+* Validates that a value is one of the five valid job statuses: `'pending'`,
+* `'processing'`, `'completed'`, `'failed'`, or `'cancelled'`. Useful for runtime validation
 * of user input or external data.
 *
 * @param value - The value to check
@@ -192,6 +206,26 @@ function isFailedJob(job) {
 	return job.status === JobStatus.FAILED;
 }
 /**
+* Type guard to check if a job has been manually cancelled.
+*
+* A convenience helper for checking if a job was cancelled by an operator.
+* Equivalent to `job.status === JobStatus.CANCELLED` but with better semantics.
+*
+* @template T - The type of the job's data payload
+* @param job - The job to check
+* @returns `true` if the job status is `'cancelled'`
+*
+* @example Filter cancelled jobs
+* ```typescript
+* const jobs = await monque.getJobs();
+* const cancelledJobs = jobs.filter(isCancelledJob);
+* console.log(`${cancelledJobs.length} jobs were cancelled`);
+* ```
+*/
+function isCancelledJob(job) {
+	return job.status === JobStatus.CANCELLED;
+}
+/**
 * Type guard to check if a job is a recurring scheduled job.
 *
 * A recurring job has a `repeatInterval` cron expression and will be automatically
@@ -220,6 +254,198 @@ function isRecurringJob(job) {
 	return job.repeatInterval !== void 0 && job.repeatInterval !== null;
 }
 
+//#endregion
+//#region src/shared/errors.ts
+/**
+* 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);
+*   }
+* }
+* ```
+*/
+var MonqueError = class MonqueError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "MonqueError";
+		/* 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);
+*   }
+* }
+* ```
+*/
+var InvalidCronError = class InvalidCronError extends MonqueError {
+	constructor(expression, message) {
+		super(message);
+		this.expression = expression;
+		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');
+*   }
+* }
+* ```
+*/
+var ConnectionError = class ConnectionError extends MonqueError {
+	constructor(message, options) {
+		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);
+*   }
+* }
+* ```
+*/
+var ShutdownTimeoutError = class ShutdownTimeoutError extends MonqueError {
+	constructor(message, incompleteJobs) {
+		super(message);
+		this.incompleteJobs = incompleteJobs;
+		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 });
+* ```
+*/
+var WorkerRegistrationError = class WorkerRegistrationError extends MonqueError {
+	constructor(message, jobName) {
+		super(message);
+		this.jobName = jobName;
+		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}`);
+*   }
+* }
+* ```
+*/
+var JobStateError = class JobStateError extends MonqueError {
+	constructor(message, jobId, currentStatus, attemptedAction) {
+		super(message);
+		this.jobId = jobId;
+		this.currentStatus = currentStatus;
+		this.attemptedAction = attemptedAction;
+		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');
+*   }
+* }
+* ```
+*/
+var InvalidCursorError = class InvalidCursorError extends MonqueError {
+	constructor(message) {
+		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');
+*   }
+* }
+* ```
+*/
+var AggregationTimeoutError = class AggregationTimeoutError extends MonqueError {
+	constructor(message = "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);
+	}
+};
+
 //#endregion
 //#region src/shared/utils/backoff.ts
 /**
@@ -332,764 +558,1853 @@ function validateCronExpression(expression) {
 	}
 }
 function handleCronParseError(expression, error) {
-	throw new require_errors.InvalidCronError(expression, `Invalid cron expression "${expression}": ${error instanceof Error ? error.message : "Unknown parsing error"}. Expected 5-field format: "minute hour day-of-month month day-of-week" or predefined expression (e.g. @daily). Example: "0 9 * * 1" (every Monday at 9am)`);
+	throw new InvalidCronError(expression, `Invalid cron expression "${expression}": ${error instanceof Error ? error.message : "Unknown parsing error"}. Expected 5-field format: "minute hour day-of-month month day-of-week" or predefined expression (e.g. @daily). Example: "0 9 * * 1" (every Monday at 9am)`);
 }
 
 //#endregion
-//#region src/scheduler/monque.ts
-/**
-* Default configuration values
-*/
-const DEFAULTS = {
-	collectionName: "monque_jobs",
-	pollInterval: 1e3,
-	maxRetries: 10,
-	baseRetryInterval: 1e3,
-	shutdownTimeout: 3e4,
-	defaultConcurrency: 5,
-	lockTimeout: 18e5,
-	recoverStaleJobs: true,
-	heartbeatInterval: 3e4,
-	retentionInterval: 36e5
-};
+//#region src/scheduler/helpers.ts
 /**
-* Monque - MongoDB-backed job scheduler
-*
-* A type-safe job scheduler with atomic locking, exponential backoff, cron scheduling,
-* stale job recovery, and event-driven observability. Built on native MongoDB driver.
-*
-* @example Complete lifecycle
-* ```;
-typescript
-*
-
-import { Monque } from '@monque/core';
-
-*
-
-import { MongoClient } from 'mongodb';
-
-*
-*
-const client = new MongoClient('mongodb://localhost:27017');
-* await client.connect()
-*
-const db = client.db('myapp');
-*
-* // Create instance with options
-*
-const monque = new Monque(db, {
-*   collectionName: 'jobs',
-*   pollInterval: 1000,
-*   maxRetries: 10,
-*   shutdownTimeout: 30000,
-* });
-*
-* // Initialize (sets up indexes and recovers stale jobs)
-* await monque.initialize()
-*
-* // Register workers with type safety
-*
-type EmailJob = {};
-*   to: string
-*   subject: string
-*   body: string
-* }
+* Build a MongoDB query filter from a JobSelector.
 *
-* monque.register<EmailJob>('send-email', async (job) =>
-{
-*   await emailService.send(job.data.to, job.data.subject, job.data.body)
+* Translates the high-level `JobSelector` interface into a MongoDB `Filter<Document>`.
+* Handles array values for status (using `$in`) and date range filtering.
 *
+* @param filter - The user-provided job selector
+* @returns A standard MongoDB filter object
+*/
+function buildSelectorQuery(filter) {
+	const query = {};
+	if (filter.name) query["name"] = filter.name;
+	if (filter.status) if (Array.isArray(filter.status)) query["status"] = { $in: filter.status };
+	else query["status"] = filter.status;
+	if (filter.olderThan || filter.newerThan) {
+		query["createdAt"] = {};
+		if (filter.olderThan) query["createdAt"].$lt = filter.olderThan;
+		if (filter.newerThan) query["createdAt"].$gt = filter.newerThan;
+	}
+	return query;
 }
-)
+/**
+* Encode an ObjectId and direction into an opaque cursor string.
 *
-* // Monitor events for observability
-* monque.on('job:complete', (
-{
-job, duration;
+* Format: `prefix` + `base64url(objectId)`
+* Prefix: 'F' (forward) or 'B' (backward)
+*
+* @param id - The job ID to use as the cursor anchor (exclusive)
+* @param direction - 'forward' or 'backward'
+* @returns Base64url-encoded cursor string
+*/
+function encodeCursor(id, direction) {
+	return (direction === "forward" ? "F" : "B") + Buffer.from(id.toHexString(), "hex").toString("base64url");
 }
-) =>
-{
-*   logger.info(`Job $job.namecompleted in $durationms`);
-* });
+/**
+* Decode an opaque cursor string into an ObjectId and direction.
 *
-* monque.on('job:fail', ({ job, error, willRetry }) => {
-*   logger.error(`Job $job.namefailed:`, error);
-* });
+* Validates format and returns the components.
 *
-* // Start processing
-* monque.start();
+* @param cursor - The opaque cursor string
+* @returns The decoded ID and direction
+* @throws {InvalidCursorError} If the cursor format is invalid or ID is malformed
+*/
+function decodeCursor(cursor) {
+	if (!cursor || cursor.length < 2) throw new InvalidCursorError("Cursor is empty or too short");
+	const prefix = cursor.charAt(0);
+	const payload = cursor.slice(1);
+	let direction;
+	if (prefix === "F") direction = CursorDirection.FORWARD;
+	else if (prefix === "B") direction = CursorDirection.BACKWARD;
+	else throw new InvalidCursorError(`Invalid cursor prefix: ${prefix}`);
+	try {
+		const hex = Buffer.from(payload, "base64url").toString("hex");
+		if (hex.length !== 24) throw new InvalidCursorError("Invalid length");
+		return {
+			id: new mongodb.ObjectId(hex),
+			direction
+		};
+	} catch (error) {
+		if (error instanceof InvalidCursorError) throw error;
+		throw new InvalidCursorError("Invalid cursor payload");
+	}
+}
+
+//#endregion
+//#region src/scheduler/services/change-stream-handler.ts
+/**
+* Internal service for MongoDB Change Stream lifecycle.
 *
-* // Enqueue jobs
-* await monque.enqueue('send-email', {
-*   to: 'user@example.com',
-*   subject: 'Welcome!',
-*   body: 'Thanks for signing up.'
-* });
+* Provides real-time job notifications when available, with automatic
+* reconnection and graceful fallback to polling-only mode.
 *
-* // Graceful shutdown
-* process.on('SIGTERM', async () => {
-*   await monque.stop();
-*   await client.close();
-*   process.exit(0);
-* });
-* ```
+* @internal Not part of public API.
 */
-var Monque = class extends node_events.EventEmitter {
-	db;
-	options;
-	collection = null;
-	workers = /* @__PURE__ */ new Map();
-	pollIntervalId = null;
-	heartbeatIntervalId = null;
-	cleanupIntervalId = null;
-	isRunning = false;
-	isInitialized = false;
-	/**
-	* MongoDB Change Stream for real-time job notifications.
-	* When available, provides instant job processing without polling delay.
-	*/
+var ChangeStreamHandler = class {
+	/** MongoDB Change Stream for real-time job notifications */
 	changeStream = null;
-	/**
-	* Number of consecutive reconnection attempts for change stream.
-	* Used for exponential backoff during reconnection.
-	*/
-	changeStreamReconnectAttempts = 0;
-	/**
-	* Maximum reconnection attempts before falling back to polling-only mode.
-	*/
-	maxChangeStreamReconnectAttempts = 3;
-	/**
-	* Debounce timer for change stream event processing.
-	* Prevents claim storms when multiple events arrive in quick succession.
-	*/
-	changeStreamDebounceTimer = null;
-	/**
-	* Whether the scheduler is currently using change streams for notifications.
-	*/
+	/** Number of consecutive reconnection attempts */
+	reconnectAttempts = 0;
+	/** Maximum reconnection attempts before falling back to polling-only mode */
+	maxReconnectAttempts = 3;
+	/** Debounce timer for change stream event processing */
+	debounceTimer = null;
+	/** Timer ID for reconnection with exponential backoff */
+	reconnectTimer = null;
+	/** Whether the scheduler is currently using change streams */
 	usingChangeStreams = false;
-	/**
-	* Timer ID for change stream reconnection with exponential backoff.
-	* Tracked to allow cancellation during shutdown.
-	*/
-	changeStreamReconnectTimer = null;
-	constructor(db, options = {}) {
-		super();
-		this.db = db;
-		this.options = {
-			collectionName: options.collectionName ?? DEFAULTS.collectionName,
-			pollInterval: options.pollInterval ?? DEFAULTS.pollInterval,
-			maxRetries: options.maxRetries ?? DEFAULTS.maxRetries,
-			baseRetryInterval: options.baseRetryInterval ?? DEFAULTS.baseRetryInterval,
-			shutdownTimeout: options.shutdownTimeout ?? DEFAULTS.shutdownTimeout,
-			defaultConcurrency: options.defaultConcurrency ?? DEFAULTS.defaultConcurrency,
-			lockTimeout: options.lockTimeout ?? DEFAULTS.lockTimeout,
-			recoverStaleJobs: options.recoverStaleJobs ?? DEFAULTS.recoverStaleJobs,
-			maxBackoffDelay: options.maxBackoffDelay,
-			schedulerInstanceId: options.schedulerInstanceId ?? (0, node_crypto.randomUUID)(),
-			heartbeatInterval: options.heartbeatInterval ?? DEFAULTS.heartbeatInterval,
-			jobRetention: options.jobRetention
-		};
+	constructor(ctx, onPoll) {
+		this.ctx = ctx;
+		this.onPoll = onPoll;
 	}
 	/**
-	* Initialize the scheduler by setting up the MongoDB collection and indexes.
-	* Must be called before start().
+	* Set up MongoDB Change Stream for real-time job notifications.
 	*
-	* @throws {ConnectionError} If collection or index creation fails
+	* 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.
 	*/
-	async initialize() {
-		if (this.isInitialized) return;
+	setup() {
+		if (!this.ctx.isRunning()) return;
 		try {
-			this.collection = this.db.collection(this.options.collectionName);
-			await this.createIndexes();
-			if (this.options.recoverStaleJobs) await this.recoverStaleJobs();
-			this.isInitialized = true;
+			this.changeStream = this.ctx.collection.watch([{ $match: { $or: [{ operationType: "insert" }, {
+				operationType: "update",
+				"updateDescription.updatedFields.status": { $exists: true }
+			}] } }], { fullDocument: "updateLookup" });
+			this.changeStream.on("change", (change) => {
+				this.handleEvent(change);
+			});
+			this.changeStream.on("error", (error) => {
+				this.ctx.emit("changestream:error", { error });
+				this.handleError(error);
+			});
+			this.usingChangeStreams = true;
+			this.reconnectAttempts = 0;
+			this.ctx.emit("changestream:connected", void 0);
 		} catch (error) {
-			throw new require_errors.ConnectionError(`Failed to initialize Monque: ${error instanceof Error ? error.message : "Unknown error during initialization"}`);
+			this.usingChangeStreams = false;
+			const reason = error instanceof Error ? error.message : "Unknown error";
+			this.ctx.emit("changestream:fallback", { reason });
 		}
 	}
 	/**
-	* Create required MongoDB indexes for efficient job processing.
+	* Handle a change stream event by triggering a debounced poll.
 	*
-	* The following indexes are created:
-	* - `{status, nextRunAt}` - For efficient job polling queries
-	* - `{name, uniqueKey}` - Partial unique index for deduplication (pending/processing only)
-	* - `{name, status}` - For job lookup by type
-	* - `{claimedBy, status}` - For finding jobs owned by a specific scheduler instance
-	* - `{lastHeartbeat, status}` - For monitoring/debugging queries (e.g., inspecting heartbeat age)
-	* - `{status, nextRunAt, claimedBy}` - For atomic claim queries (find unclaimed pending jobs)
-	* - `{lockedAt, lastHeartbeat, status}` - Supports recovery scans and monitoring access patterns
+	* 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
 	*/
-	async createIndexes() {
-		if (!this.collection) throw new require_errors.ConnectionError("Collection not initialized");
-		await this.collection.createIndex({
-			status: 1,
-			nextRunAt: 1
-		}, { background: true });
-		await this.collection.createIndex({
-			name: 1,
-			uniqueKey: 1
-		}, {
-			unique: true,
-			partialFilterExpression: {
-				uniqueKey: { $exists: true },
-				status: { $in: [JobStatus.PENDING, JobStatus.PROCESSING] }
-			},
-			background: true
-		});
-		await this.collection.createIndex({
-			name: 1,
-			status: 1
-		}, { background: true });
-		await this.collection.createIndex({
-			claimedBy: 1,
-			status: 1
-		}, { background: true });
-		await this.collection.createIndex({
-			lastHeartbeat: 1,
-			status: 1
-		}, { background: true });
-		await this.collection.createIndex({
-			status: 1,
-			nextRunAt: 1,
-			claimedBy: 1
-		}, { background: true });
-		await this.collection.createIndex({
-			status: 1,
-			lockedAt: 1,
-			lastHeartbeat: 1
-		}, { background: true });
+	handleEvent(change) {
+		if (!this.ctx.isRunning()) return;
+		const isInsert = change.operationType === "insert";
+		const isUpdate = change.operationType === "update";
+		const isPendingStatus = ("fullDocument" in change ? change.fullDocument : void 0)?.["status"] === JobStatus.PENDING;
+		if (isInsert || isUpdate && isPendingStatus) {
+			if (this.debounceTimer) clearTimeout(this.debounceTimer);
+			this.debounceTimer = setTimeout(() => {
+				this.debounceTimer = null;
+				this.onPoll().catch((error) => {
+					this.ctx.emit("job:error", { error });
+				});
+			}, 100);
+		}
 	}
 	/**
-	* Recover stale jobs that were left in 'processing' status.
-	* A job is considered stale if its `lockedAt` timestamp exceeds the configured `lockTimeout`.
-	* Stale jobs are reset to 'pending' so they can be picked up by workers again.
+	* 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
 	*/
-	async recoverStaleJobs() {
-		if (!this.collection) return;
-		const staleThreshold = new Date(Date.now() - this.options.lockTimeout);
-		const result = await this.collection.updateMany({
-			status: JobStatus.PROCESSING,
-			lockedAt: { $lt: staleThreshold }
+	handleError(error) {
+		if (!this.ctx.isRunning()) return;
+		this.reconnectAttempts++;
+		if (this.reconnectAttempts > this.maxReconnectAttempts) {
+			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;
+		}
+		const delay = 2 ** (this.reconnectAttempts - 1) * 1e3;
+		if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+		this.reconnectTimer = setTimeout(() => {
+			this.reconnectTimer = null;
+			if (this.ctx.isRunning()) {
+				if (this.changeStream) {
+					this.changeStream.close().catch(() => {});
+					this.changeStream = null;
+				}
+				this.setup();
+			}
+		}, delay);
+	}
+	/**
+	* Close the change stream cursor and emit closed event.
+	*/
+	async close() {
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer);
+			this.debounceTimer = null;
+		}
+		if (this.reconnectTimer) {
+			clearTimeout(this.reconnectTimer);
+			this.reconnectTimer = null;
+		}
+		if (this.changeStream) {
+			try {
+				await this.changeStream.close();
+			} catch {}
+			this.changeStream = null;
+			if (this.usingChangeStreams) this.ctx.emit("changestream:closed", void 0);
+		}
+		this.usingChangeStreams = false;
+		this.reconnectAttempts = 0;
+	}
+	/**
+	* Check if change streams are currently active.
+	*/
+	isActive() {
+		return this.usingChangeStreams;
+	}
+};
+
+//#endregion
+//#region src/scheduler/services/job-manager.ts
+/**
+* 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.
+*/
+var JobManager = class {
+	constructor(ctx) {
+		this.ctx = ctx;
+	}
+	/**
+	* 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) {
+		if (!mongodb.ObjectId.isValid(jobId)) return null;
+		const _id = new mongodb.ObjectId(jobId);
+		const jobDoc = await this.ctx.collection.findOne({ _id });
+		if (!jobDoc) return null;
+		const currentJob = jobDoc;
+		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: /* @__PURE__ */ new Date()
+		} }, { returnDocument: "after" });
+		if (!result) 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) {
+		if (!mongodb.ObjectId.isValid(jobId)) return null;
+		const _id = new mongodb.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"];
+		const result = await this.ctx.collection.findOneAndUpdate({
+			_id,
+			status: { $in: [JobStatus.FAILED, JobStatus.CANCELLED] }
 		}, {
 			$set: {
 				status: JobStatus.PENDING,
+				failCount: 0,
+				nextRunAt: /* @__PURE__ */ new Date(),
 				updatedAt: /* @__PURE__ */ 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
 		});
-		if (result.modifiedCount > 0) this.emit("stale:recovered", { count: result.modifiedCount });
+		return job;
 	}
 	/**
-	* Clean up old completed and failed jobs based on retention policy.
+	* Reschedule a pending job to run at a different time.
 	*
-	* - Removes completed jobs older than `jobRetention.completed`
-	* - Removes failed jobs older than `jobRetention.failed`
+	* Only works for jobs in 'pending' status.
 	*
-	* The cleanup runs concurrently for both statuses if configured.
+	* @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
 	*
-	* @returns Promise resolving when all deletion operations complete
+	* @example Delay a job by 1 hour
+	* ```typescript
+	* const nextHour = new Date(Date.now() + 60 * 60 * 1000);
+	* await monque.rescheduleJob(jobId, nextHour);
+	* ```
 	*/
-	async cleanupJobs() {
-		if (!this.collection || !this.options.jobRetention) return;
-		const { completed, failed } = this.options.jobRetention;
-		const now = Date.now();
-		const deletions = [];
-		if (completed) {
-			const cutoff = new Date(now - completed);
-			deletions.push(this.collection.deleteMany({
-				status: JobStatus.COMPLETED,
-				updatedAt: { $lt: cutoff }
-			}));
-		}
-		if (failed) {
-			const cutoff = new Date(now - failed);
-			deletions.push(this.collection.deleteMany({
-				status: JobStatus.FAILED,
-				updatedAt: { $lt: cutoff }
-			}));
-		}
-		if (deletions.length > 0) await Promise.all(deletions);
+	async rescheduleJob(jobId, runAt) {
+		if (!mongodb.ObjectId.isValid(jobId)) return null;
+		const _id = new mongodb.ObjectId(jobId);
+		const currentJobDoc = await this.ctx.collection.findOne({ _id });
+		if (!currentJobDoc) return null;
+		const currentJob = currentJobDoc;
+		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: /* @__PURE__ */ new Date()
+		} }, { returnDocument: "after" });
+		if (!result) throw new JobStateError("Job status changed during reschedule attempt", jobId, "unknown", "reschedule");
+		return this.ctx.documentToPersistedJob(result);
 	}
 	/**
-	* Enqueue a job for processing.
-	*
-	* Jobs are stored in MongoDB and processed by registered workers. Supports
-	* delayed execution via `runAt` and deduplication via `uniqueKey`.
+	* Permanently delete a job.
 	*
-	* 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`.
+	* This action is irreversible. Emits a 'job:deleted' event upon success.
+	* Can delete a job in any state.
 	*
-	* @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
+	* @param jobId - The ID of the job to delete
+	* @returns true if deleted, false if job not found
 	*
-	* @example Basic job enqueueing
+	* @example Delete a cleanup job
 	* ```typescript
-	* await monque.enqueue('send-email', {
-	*   to: 'user@example.com',
-	*   subject: 'Welcome!',
-	*   body: 'Thanks for signing up.'
-	* });
+	* const deleted = await monque.deleteJob(jobId);
+	* if (deleted) {
+	*   console.log('Job permanently removed');
+	* }
 	* ```
+	*/
+	async deleteJob(jobId) {
+		if (!mongodb.ObjectId.isValid(jobId)) return false;
+		const _id = new mongodb.ObjectId(jobId);
+		if ((await this.ctx.collection.deleteOne({ _id })).deletedCount > 0) {
+			this.ctx.emit("job:deleted", { jobId });
+			return true;
+		}
+		return false;
+	}
+	/**
+	* Cancel multiple jobs matching the given filter.
 	*
-	* @example Delayed execution
-	* ```typescript
-	* const oneHourLater = new Date(Date.now() + 3600000);
-	* await monque.enqueue('reminder', { message: 'Check in!' }, {
-	*   runAt: oneHourLater
-	* });
-	* ```
+	* 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.
 	*
-	* @example Prevent duplicates with unique key
+	* @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
-	* await monque.enqueue('sync-user', { userId: '123' }, {
-	*   uniqueKey: 'sync-user-123'
+	* const result = await monque.cancelJobs({
+	*   name: 'email-queue',
+	*   status: 'pending'
 	* });
-	* // Subsequent enqueues with same uniqueKey return existing pending/processing job
+	* console.log(`Cancelled ${result.count} jobs`);
 	* ```
 	*/
-	async enqueue(name, data, options = {}) {
-		this.ensureInitialized();
-		const now = /* @__PURE__ */ new Date();
-		const job = {
-			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) {
-				if (!this.collection) throw new require_errors.ConnectionError("Failed to enqueue job: collection not available");
-				const result$1 = await this.collection.findOneAndUpdate({
-					name,
-					uniqueKey: options.uniqueKey,
-					status: { $in: [JobStatus.PENDING, JobStatus.PROCESSING] }
-				}, { $setOnInsert: job }, {
-					upsert: true,
-					returnDocument: "after"
+	async cancelJobs(filter) {
+		const baseQuery = buildSelectorQuery(filter);
+		const errors = [];
+		const cancelledIds = [];
+		const cursor = this.ctx.collection.find(baseQuery);
+		for await (const doc of cursor) {
+			const job = doc;
+			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}'`
 				});
-				if (!result$1) throw new require_errors.ConnectionError("Failed to enqueue job: findOneAndUpdate returned no document");
-				return this.documentToPersistedJob(result$1);
+				continue;
 			}
-			const result = await this.collection?.insertOne(job);
-			if (!result) throw new require_errors.ConnectionError("Failed to enqueue job: collection not available");
-			return {
-				...job,
-				_id: result.insertedId
-			};
-		} catch (error) {
-			if (error instanceof require_errors.ConnectionError) throw error;
-			throw new require_errors.ConnectionError(`Failed to enqueue job: ${error instanceof Error ? error.message : "Unknown error during enqueue"}`, error instanceof Error ? { cause: error } : void 0);
+			if (job.status === JobStatus.CANCELLED) {
+				cancelledIds.push(jobId);
+				continue;
+			}
+			if (await this.ctx.collection.findOneAndUpdate({
+				_id: job._id,
+				status: JobStatus.PENDING
+			}, { $set: {
+				status: JobStatus.CANCELLED,
+				updatedAt: /* @__PURE__ */ new Date()
+			} }, { returnDocument: "after" })) cancelledIds.push(jobId);
+			else 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
+		};
 	}
 	/**
-	* Enqueue a job for immediate processing.
+	* Retry multiple jobs matching the given filter.
 	*
-	* 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`).
+	* 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.
 	*
-	* @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
+	* @param filter - Selector for which jobs to retry (name, status, date range)
+	* @returns Result with count of retried jobs and any errors encountered
 	*
-	* @example Send email immediately
+	* @example Retry all failed jobs
 	* ```typescript
-	* await monque.now('send-email', {
-	*   to: 'admin@example.com',
-	*   subject: 'Alert',
-	*   body: 'Immediate attention required'
+	* const result = await monque.retryJobs({
+	*   status: 'failed'
 	* });
-	* ```
-	*
-	* @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
+	* console.log(`Retried ${result.count} jobs`);
 	* ```
 	*/
-	async now(name, data) {
-		return this.enqueue(name, data, { runAt: /* @__PURE__ */ 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.
+	async retryJobs(filter) {
+		const baseQuery = buildSelectorQuery(filter);
+		const errors = [];
+		const retriedIds = [];
+		const cursor = this.ctx.collection.find(baseQuery);
+		for await (const doc of cursor) {
+			const job = doc;
+			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;
+			}
+			if (await this.ctx.collection.findOneAndUpdate({
+				_id: job._id,
+				status: { $in: [JobStatus.FAILED, JobStatus.CANCELLED] }
+			}, {
+				$set: {
+					status: JobStatus.PENDING,
+					failCount: 0,
+					nextRunAt: /* @__PURE__ */ new Date(),
+					updatedAt: /* @__PURE__ */ new Date()
+				},
+				$unset: {
+					failReason: "",
+					lockedAt: "",
+					claimedBy: "",
+					lastHeartbeat: "",
+					heartbeatInterval: ""
+				}
+			}, { returnDocument: "after" })) 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) {
+		const query = buildSelectorQuery(filter);
+		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: []
+		};
+	}
+};
+
+//#endregion
+//#region src/scheduler/services/job-processor.ts
+/**
+* Internal service for job processing and execution.
+*
+* Manages the poll loop, atomic job acquisition, handler execution,
+* and job completion/failure with exponential backoff retry logic.
+*
+* @internal Not part of public API.
+*/
+var JobProcessor = class {
+	constructor(ctx) {
+		this.ctx = ctx;
+	}
+	/**
+	* Poll for available jobs and process them.
+	*
+	* Called at regular intervals (configured by `pollInterval`). For each registered worker,
+	* attempts to acquire jobs up to the worker's available concurrency slots.
+	* Aborts early if the scheduler is stopping (`isRunning` is false).
+	*/
+	async poll() {
+		if (!this.ctx.isRunning()) return;
+		for (const [name, worker] of this.ctx.workers) {
+			const availableSlots = worker.concurrency - worker.activeJobs.size;
+			if (availableSlots <= 0) continue;
+			for (let i = 0; i < availableSlots; i++) {
+				if (!this.ctx.isRunning()) return;
+				const job = await this.acquireJob(name);
+				if (job) this.processJob(job, worker).catch((error) => {
+					this.ctx.emit("job:error", {
+						error,
+						job
+					});
+				});
+				else break;
+			}
+		}
+	}
+	/**
+	* Atomically acquire a pending job for processing using the claimedBy pattern.
+	*
+	* Uses MongoDB's `findOneAndUpdate` with atomic operations to ensure only one scheduler
+	* instance can claim a job. The query ensures the job is:
+	* - In pending status
+	* - Has nextRunAt <= now
+	* - Is not claimed by another instance (claimedBy is null/undefined)
+	*
+	* Returns `null` immediately if scheduler is stopping (`isRunning` is false).
+	*
+	* @param name - The job type to acquire
+	* @returns The acquired job with updated status, claimedBy, and heartbeat info, or `null` if no jobs available
+	*/
+	async acquireJob(name) {
+		if (!this.ctx.isRunning()) return null;
+		const now = /* @__PURE__ */ new Date();
+		const result = await this.ctx.collection.findOneAndUpdate({
+			name,
+			status: JobStatus.PENDING,
+			nextRunAt: { $lte: now },
+			$or: [{ claimedBy: null }, { claimedBy: { $exists: false } }]
+		}, { $set: {
+			status: JobStatus.PROCESSING,
+			claimedBy: this.ctx.instanceId,
+			lockedAt: now,
+			lastHeartbeat: now,
+			heartbeatInterval: this.ctx.options.heartbeatInterval,
+			updatedAt: now
+		} }, {
+			sort: { nextRunAt: 1 },
+			returnDocument: "after"
+		});
+		if (!this.ctx.isRunning()) return null;
+		if (!result) return null;
+		return this.ctx.documentToPersistedJob(result);
+	}
+	/**
+	* Execute a job using its registered worker handler.
+	*
+	* Tracks the job as active during processing, emits lifecycle events, and handles
+	* both success and failure cases. On success, calls `completeJob()`. On failure,
+	* calls `failJob()` which implements exponential backoff retry logic.
+	*
+	* @param job - The job to process
+	* @param worker - The worker registration containing the handler and active job tracking
+	*/
+	async processJob(job, worker) {
+		const jobId = job._id.toString();
+		worker.activeJobs.set(jobId, job);
+		const startTime = Date.now();
+		this.ctx.emit("job:start", job);
+		try {
+			await worker.handler(job);
+			const duration = Date.now() - startTime;
+			await this.completeJob(job);
+			this.ctx.emit("job:complete", {
+				job,
+				duration
+			});
+		} catch (error) {
+			const err = error instanceof Error ? error : new Error(String(error));
+			await this.failJob(job, err);
+			const willRetry = job.failCount + 1 < this.ctx.options.maxRetries;
+			this.ctx.emit("job:fail", {
+				job,
+				error: err,
+				willRetry
+			});
+		} finally {
+			worker.activeJobs.delete(jobId);
+		}
+	}
+	/**
+	* Mark a job as completed successfully.
+	*
+	* For recurring jobs (with `repeatInterval`), schedules the next run based on the cron
+	* expression and resets `failCount` to 0. For one-time jobs, sets status to `completed`.
+	* Clears `lockedAt` and `failReason` fields in both cases.
+	*
+	* @param job - The job that completed successfully
+	*/
+	async completeJob(job) {
+		if (!isPersistedJob(job)) return;
+		if (job.repeatInterval) {
+			const nextRunAt = getNextCronDate(job.repeatInterval);
+			await this.ctx.collection.updateOne({ _id: job._id }, {
+				$set: {
+					status: JobStatus.PENDING,
+					nextRunAt,
+					failCount: 0,
+					updatedAt: /* @__PURE__ */ new Date()
+				},
+				$unset: {
+					lockedAt: "",
+					claimedBy: "",
+					lastHeartbeat: "",
+					heartbeatInterval: "",
+					failReason: ""
+				}
+			});
+		} else {
+			await this.ctx.collection.updateOne({ _id: job._id }, {
+				$set: {
+					status: JobStatus.COMPLETED,
+					updatedAt: /* @__PURE__ */ new Date()
+				},
+				$unset: {
+					lockedAt: "",
+					claimedBy: "",
+					lastHeartbeat: "",
+					heartbeatInterval: "",
+					failReason: ""
+				}
+			});
+			job.status = JobStatus.COMPLETED;
+		}
+	}
+	/**
+	* Handle job failure with exponential backoff retry logic.
+	*
+	* Increments `failCount` and calculates next retry time using exponential backoff:
+	* `nextRunAt = 2^failCount × baseRetryInterval` (capped by optional `maxBackoffDelay`).
+	*
+	* If `failCount >= maxRetries`, marks job as permanently `failed`. Otherwise, resets
+	* to `pending` status for retry. Stores error message in `failReason` field.
+	*
+	* @param job - The job that failed
+	* @param error - The error that caused the failure
+	*/
+	async failJob(job, error) {
+		if (!isPersistedJob(job)) return;
+		const newFailCount = job.failCount + 1;
+		if (newFailCount >= this.ctx.options.maxRetries) await this.ctx.collection.updateOne({ _id: job._id }, {
+			$set: {
+				status: JobStatus.FAILED,
+				failCount: newFailCount,
+				failReason: error.message,
+				updatedAt: /* @__PURE__ */ new Date()
+			},
+			$unset: {
+				lockedAt: "",
+				claimedBy: "",
+				lastHeartbeat: "",
+				heartbeatInterval: ""
+			}
+		});
+		else {
+			const nextRunAt = calculateBackoff(newFailCount, this.ctx.options.baseRetryInterval, this.ctx.options.maxBackoffDelay);
+			await this.ctx.collection.updateOne({ _id: job._id }, {
+				$set: {
+					status: JobStatus.PENDING,
+					failCount: newFailCount,
+					failReason: error.message,
+					nextRunAt,
+					updatedAt: /* @__PURE__ */ new Date()
+				},
+				$unset: {
+					lockedAt: "",
+					claimedBy: "",
+					lastHeartbeat: "",
+					heartbeatInterval: ""
+				}
+			});
+		}
+	}
+	/**
+	* Update heartbeats for all jobs claimed by this scheduler instance.
+	*
+	* This method runs periodically while the scheduler is running to indicate
+	* that jobs are still being actively processed.
+	*
+	* `lastHeartbeat` is primarily an observability signal (monitoring/debugging).
+	* Stale recovery is based on `lockedAt` + `lockTimeout`.
+	*/
+	async updateHeartbeats() {
+		if (!this.ctx.isRunning()) return;
+		const now = /* @__PURE__ */ new Date();
+		await this.ctx.collection.updateMany({
+			claimedBy: this.ctx.instanceId,
+			status: JobStatus.PROCESSING
+		}, { $set: {
+			lastHeartbeat: now,
+			updatedAt: now
+		} });
+	}
+};
+
+//#endregion
+//#region src/scheduler/services/job-query.ts
+/**
+* Internal service for job query operations.
+*
+* Provides read-only access to jobs with filtering and cursor-based pagination.
+* All queries use efficient index-backed access patterns.
+*
+* @internal Not part of public API - use Monque class methods instead.
+*/
+var JobQueryService = class {
+	constructor(ctx) {
+		this.ctx = ctx;
+	}
+	/**
+	* Get a single job by its MongoDB ObjectId.
+	*
+	* Useful for retrieving job details when you have a job ID from events,
+	* logs, or stored references.
+	*
+	* @template T - The expected type of the job data payload
+	* @param id - The job's ObjectId
+	* @returns Promise resolving to the job if found, null otherwise
+	* @throws {ConnectionError} If scheduler not initialized
+	*
+	* @example Look up job from event
+	* ```typescript
+	* monque.on('job:fail', async ({ job }) => {
+	*   // Later, retrieve the job to check its status
+	*   const currentJob = await monque.getJob(job._id);
+	*   console.log(`Job status: ${currentJob?.status}`);
+	* });
+	* ```
+	*
+	* @example Admin endpoint
+	* ```typescript
+	* app.get('/jobs/:id', async (req, res) => {
+	*   const job = await monque.getJob(new ObjectId(req.params.id));
+	*   if (!job) {
+	*     return res.status(404).json({ error: 'Job not found' });
+	*   }
+	*   res.json(job);
+	* });
+	* ```
+	*/
+	async getJob(id) {
+		try {
+			const doc = await this.ctx.collection.findOne({ _id: id });
+			if (!doc) return null;
+			return this.ctx.documentToPersistedJob(doc);
+		} catch (error) {
+			throw new ConnectionError(`Failed to get job: ${error instanceof Error ? error.message : "Unknown error during getJob"}`, error instanceof Error ? { cause: error } : void 0);
+		}
+	}
+	/**
+	* Query jobs from the queue with optional filters.
+	*
+	* Provides read-only access to job data for monitoring, debugging, and
+	* administrative purposes. Results are ordered by `nextRunAt` ascending.
+	*
+	* @template T - The expected type of the job data payload
+	* @param filter - Optional filter criteria
+	* @returns Promise resolving to array of matching jobs
+	* @throws {ConnectionError} If scheduler not initialized
+	*
+	* @example Get all pending jobs
+	* ```typescript
+	* const pendingJobs = await monque.getJobs({ status: JobStatus.PENDING });
+	* console.log(`${pendingJobs.length} jobs waiting`);
+	* ```
+	*
+	* @example Get failed email jobs
+	* ```typescript
+	* const failedEmails = await monque.getJobs({
+	*   name: 'send-email',
+	*   status: JobStatus.FAILED,
+	* });
+	* for (const job of failedEmails) {
+	*   console.error(`Job ${job._id} failed: ${job.failReason}`);
+	* }
+	* ```
+	*
+	* @example Paginated job listing
+	* ```typescript
+	* const page1 = await monque.getJobs({ limit: 50, skip: 0 });
+	* const page2 = await monque.getJobs({ limit: 50, skip: 50 });
+	* ```
+	*
+	* @example Use with type guards from @monque/core
+	* ```typescript
+	* import { isPendingJob, isRecurringJob } from '@monque/core';
+	*
+	* const jobs = await monque.getJobs();
+	* const pendingRecurring = jobs.filter(job => isPendingJob(job) && isRecurringJob(job));
+	* ```
+	*/
+	async getJobs(filter = {}) {
+		const query = {};
+		if (filter.name !== void 0) query["name"] = filter.name;
+		if (filter.status !== void 0) if (Array.isArray(filter.status)) query["status"] = { $in: filter.status };
+		else query["status"] = filter.status;
+		const limit = filter.limit ?? 100;
+		const skip = filter.skip ?? 0;
+		try {
+			return (await this.ctx.collection.find(query).sort({ nextRunAt: 1 }).skip(skip).limit(limit).toArray()).map((doc) => this.ctx.documentToPersistedJob(doc));
+		} catch (error) {
+			throw new ConnectionError(`Failed to query jobs: ${error instanceof Error ? error.message : "Unknown error during getJobs"}`, error instanceof Error ? { cause: error } : void 0);
+		}
+	}
+	/**
+	* Get a paginated list of jobs using opaque cursors.
+	*
+	* Provides stable pagination for large job lists. Supports forward and backward
+	* navigation, filtering, and efficient database access via index-based cursor queries.
+	*
+	* @template T - The job data payload type
+	* @param options - Pagination options (cursor, limit, direction, filter)
+	* @returns Page of jobs with next/prev cursors
+	* @throws {InvalidCursorError} If the provided cursor is malformed
+	* @throws {ConnectionError} If database operation fails or scheduler not initialized
+	*
+	* @example List pending jobs
+	* ```typescript
+	* const page = await monque.getJobsWithCursor({
+	*   limit: 20,
+	*   filter: { status: 'pending' }
+	* });
+	* const jobs = page.jobs;
+	*
+	* // Get next page
+	* if (page.hasNextPage) {
+	*   const page2 = await monque.getJobsWithCursor({
+	*     cursor: page.cursor,
+	*     limit: 20
+	*   });
+	* }
+	* ```
+	*/
+	async getJobsWithCursor(options = {}) {
+		const limit = options.limit ?? 50;
+		const direction = options.direction ?? CursorDirection.FORWARD;
+		let anchorId = null;
+		if (options.cursor) anchorId = decodeCursor(options.cursor).id;
+		const query = options.filter ? buildSelectorQuery(options.filter) : {};
+		const sortDir = direction === CursorDirection.FORWARD ? 1 : -1;
+		if (anchorId) if (direction === CursorDirection.FORWARD) query._id = {
+			...query._id,
+			$gt: anchorId
+		};
+		else query._id = {
+			...query._id,
+			$lt: anchorId
+		};
+		const fetchLimit = limit + 1;
+		let docs;
+		try {
+			docs = await this.ctx.collection.find(query).sort({ _id: sortDir }).limit(fetchLimit).toArray();
+		} catch (error) {
+			throw new ConnectionError(`Failed to query jobs with cursor: ${error instanceof Error ? error.message : "Unknown error during getJobsWithCursor"}`, error instanceof Error ? { cause: error } : void 0);
+		}
+		let hasMore = false;
+		if (docs.length > limit) {
+			hasMore = true;
+			docs.pop();
+		}
+		if (direction === CursorDirection.BACKWARD) docs.reverse();
+		const jobs = docs.map((doc) => this.ctx.documentToPersistedJob(doc));
+		let nextCursor = null;
+		if (jobs.length > 0) {
+			const lastJob = jobs[jobs.length - 1];
+			if (lastJob) nextCursor = encodeCursor(lastJob._id, direction);
+		}
+		let hasNextPage = false;
+		let hasPreviousPage = false;
+		if (direction === CursorDirection.FORWARD) {
+			hasNextPage = hasMore;
+			hasPreviousPage = !!anchorId;
+		} else {
+			hasNextPage = !!anchorId;
+			hasPreviousPage = hasMore;
+		}
+		return {
+			jobs,
+			cursor: nextCursor,
+			hasNextPage,
+			hasPreviousPage
+		};
+	}
+	/**
+	* 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.
+	*
+	* @param filter - Optional filter to scope statistics by job name
+	* @returns Promise resolving to queue statistics
+	* @throws {AggregationTimeoutError} If aggregation exceeds 30 second timeout
+	* @throws {ConnectionError} If database operation fails
+	*
+	* @example Get overall queue statistics
+	* ```typescript
+	* const stats = await monque.getQueueStats();
+	* console.log(`Pending: ${stats.pending}, Failed: ${stats.failed}`);
+	* ```
+	*
+	* @example Get statistics for a specific job type
+	* ```typescript
+	* const emailStats = await monque.getQueueStats({ name: 'send-email' });
+	* console.log(`${emailStats.total} email jobs in queue`);
+	* ```
+	*/
+	async getQueueStats(filter) {
+		const matchStage = {};
+		if (filter?.name) matchStage["name"] = filter.name;
+		const pipeline = [...Object.keys(matchStage).length > 0 ? [{ $match: matchStage }] : [], { $facet: {
+			statusCounts: [{ $group: {
+				_id: "$status",
+				count: { $sum: 1 }
+			} }],
+			avgDuration: [{ $match: { status: JobStatus.COMPLETED } }, { $group: {
+				_id: null,
+				avgMs: { $avg: { $subtract: ["$updatedAt", "$createdAt"] } }
+			} }],
+			total: [{ $count: "count" }]
+		} }];
+		try {
+			const result = (await this.ctx.collection.aggregate(pipeline, { maxTimeMS: 3e4 }).toArray())[0];
+			const stats = {
+				pending: 0,
+				processing: 0,
+				completed: 0,
+				failed: 0,
+				cancelled: 0,
+				total: 0
+			};
+			if (!result) return stats;
+			const statusCounts = result["statusCounts"];
+			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;
+				}
+			}
+			const totalResult = result["total"];
+			if (totalResult.length > 0 && totalResult[0]) stats.total = totalResult[0].count;
+			const avgDurationResult = result["avgDuration"];
+			if (avgDurationResult.length > 0 && avgDurationResult[0]) {
+				const avgMs = avgDurationResult[0].avgMs;
+				if (typeof avgMs === "number" && !Number.isNaN(avgMs)) stats.avgProcessingDurationMs = Math.round(avgMs);
+			}
+			return stats;
+		} catch (error) {
+			if (error instanceof Error && error.message.includes("exceeded time limit")) throw new AggregationTimeoutError();
+			throw new ConnectionError(`Failed to get queue stats: ${error instanceof Error ? error.message : "Unknown error during getQueueStats"}`, error instanceof Error ? { cause: error } : void 0);
+		}
+	}
+};
+
+//#endregion
+//#region src/scheduler/services/job-scheduler.ts
+/**
+* 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.
+*/
+var JobScheduler = class {
+	constructor(ctx) {
+		this.ctx = ctx;
+	}
+	/**
+	* 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(name, data, options = {}) {
+		const now = /* @__PURE__ */ new Date();
+		const job = {
+			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) {
+				const result$1 = await this.ctx.collection.findOneAndUpdate({
+					name,
+					uniqueKey: options.uniqueKey,
+					status: { $in: [JobStatus.PENDING, JobStatus.PROCESSING] }
+				}, { $setOnInsert: job }, {
+					upsert: true,
+					returnDocument: "after"
+				});
+				if (!result$1) throw new ConnectionError("Failed to enqueue job: findOneAndUpdate returned no document");
+				return this.ctx.documentToPersistedJob(result$1);
+			}
+			const result = await this.ctx.collection.insertOne(job);
+			return {
+				...job,
+				_id: result.insertedId
+			};
+		} catch (error) {
+			if (error instanceof ConnectionError) throw error;
+			throw new ConnectionError(`Failed to enqueue job: ${error instanceof Error ? error.message : "Unknown error during enqueue"}`, error instanceof Error ? { cause: error } : void 0);
+		}
+	}
+	/**
+	* 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(name, data) {
+		return this.enqueue(name, data, { runAt: /* @__PURE__ */ 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(cron, name, data, options = {}) {
+		const nextRunAt = getNextCronDate(cron);
+		const now = /* @__PURE__ */ new Date();
+		const job = {
+			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) {
+				const result$1 = await this.ctx.collection.findOneAndUpdate({
+					name,
+					uniqueKey: options.uniqueKey,
+					status: { $in: [JobStatus.PENDING, JobStatus.PROCESSING] }
+				}, { $setOnInsert: job }, {
+					upsert: true,
+					returnDocument: "after"
+				});
+				if (!result$1) throw new ConnectionError("Failed to schedule job: findOneAndUpdate returned no document");
+				return this.ctx.documentToPersistedJob(result$1);
+			}
+			const result = await this.ctx.collection.insertOne(job);
+			return {
+				...job,
+				_id: result.insertedId
+			};
+		} catch (error) {
+			if (error instanceof MonqueError) throw error;
+			throw new ConnectionError(`Failed to schedule job: ${error instanceof Error ? error.message : "Unknown error during schedule"}`, error instanceof Error ? { cause: error } : void 0);
+		}
+	}
+};
+
+//#endregion
+//#region src/scheduler/monque.ts
+/**
+* Default configuration values
+*/
+const DEFAULTS = {
+	collectionName: "monque_jobs",
+	pollInterval: 1e3,
+	maxRetries: 10,
+	baseRetryInterval: 1e3,
+	shutdownTimeout: 3e4,
+	defaultConcurrency: 5,
+	lockTimeout: 18e5,
+	recoverStaleJobs: true,
+	heartbeatInterval: 3e4,
+	retentionInterval: 36e5
+};
+/**
+* Monque - MongoDB-backed job scheduler
+*
+* A type-safe job scheduler with atomic locking, exponential backoff, cron scheduling,
+* stale job recovery, and event-driven observability. Built on native MongoDB driver.
+*
+* @example Complete lifecycle
+* ```typescript
+* import { Monque } from '@monque/core';
+* import { MongoClient } from 'mongodb';
+*
+* const client = new MongoClient('mongodb://localhost:27017');
+* await client.connect();
+* const db = client.db('myapp');
+*
+* // Create instance with options
+* const monque = new Monque(db, {
+*   collectionName: 'jobs',
+*   pollInterval: 1000,
+*   maxRetries: 10,
+*   shutdownTimeout: 30000,
+* });
+*
+* // Initialize (sets up indexes and recovers stale jobs)
+* await monque.initialize();
+*
+* // Register workers with type safety
+* type EmailJob = {
+*   to: string;
+*   subject: string;
+*   body: string;
+* };
+*
+* monque.register<EmailJob>('send-email', async (job) => {
+*   await emailService.send(job.data.to, job.data.subject, job.data.body);
+* });
+*
+* // Monitor events for observability
+* monque.on('job:complete', ({ job, duration }) => {
+*   logger.info(`Job ${job.name} completed in ${duration}ms`);
+* });
+*
+* monque.on('job:fail', ({ job, error, willRetry }) => {
+*   logger.error(`Job ${job.name} failed:`, error);
+* });
+*
+* // Start processing
+* monque.start();
+*
+* // Enqueue jobs
+* await monque.enqueue('send-email', {
+*   to: 'user@example.com',
+*   subject: 'Welcome!',
+*   body: 'Thanks for signing up.'
+* });
+*
+* // Graceful shutdown
+* process.on('SIGTERM', async () => {
+*   await monque.stop();
+*   await client.close();
+*   process.exit(0);
+* });
+* ```
+*/
+var Monque = class extends node_events.EventEmitter {
+	db;
+	options;
+	collection = null;
+	workers = /* @__PURE__ */ new Map();
+	pollIntervalId = null;
+	heartbeatIntervalId = null;
+	cleanupIntervalId = null;
+	isRunning = false;
+	isInitialized = false;
+	_scheduler = null;
+	_manager = null;
+	_query = null;
+	_processor = null;
+	_changeStreamHandler = null;
+	constructor(db, options = {}) {
+		super();
+		this.db = db;
+		this.options = {
+			collectionName: options.collectionName ?? DEFAULTS.collectionName,
+			pollInterval: options.pollInterval ?? DEFAULTS.pollInterval,
+			maxRetries: options.maxRetries ?? DEFAULTS.maxRetries,
+			baseRetryInterval: options.baseRetryInterval ?? DEFAULTS.baseRetryInterval,
+			shutdownTimeout: options.shutdownTimeout ?? DEFAULTS.shutdownTimeout,
+			defaultConcurrency: options.defaultConcurrency ?? DEFAULTS.defaultConcurrency,
+			lockTimeout: options.lockTimeout ?? DEFAULTS.lockTimeout,
+			recoverStaleJobs: options.recoverStaleJobs ?? DEFAULTS.recoverStaleJobs,
+			maxBackoffDelay: options.maxBackoffDelay,
+			schedulerInstanceId: options.schedulerInstanceId ?? (0, node_crypto.randomUUID)(),
+			heartbeatInterval: options.heartbeatInterval ?? DEFAULTS.heartbeatInterval,
+			jobRetention: options.jobRetention
+		};
+	}
+	/**
+	* Initialize the scheduler by setting up the MongoDB collection and indexes.
+	* Must be called before start().
+	*
+	* @throws {ConnectionError} If collection or index creation fails
+	*/
+	async initialize() {
+		if (this.isInitialized) return;
+		try {
+			this.collection = this.db.collection(this.options.collectionName);
+			await this.createIndexes();
+			if (this.options.recoverStaleJobs) await this.recoverStaleJobs();
+			const ctx = this.buildContext();
+			this._scheduler = new JobScheduler(ctx);
+			this._manager = new JobManager(ctx);
+			this._query = new JobQueryService(ctx);
+			this._processor = new JobProcessor(ctx);
+			this._changeStreamHandler = new ChangeStreamHandler(ctx, () => this.processor.poll());
+			this.isInitialized = true;
+		} catch (error) {
+			throw new ConnectionError(`Failed to initialize Monque: ${error instanceof Error ? error.message : "Unknown error during initialization"}`);
+		}
+	}
+	/** @throws {ConnectionError} if not initialized */
+	get scheduler() {
+		if (!this._scheduler) throw new ConnectionError("Monque not initialized. Call initialize() first.");
+		return this._scheduler;
+	}
+	/** @throws {ConnectionError} if not initialized */
+	get manager() {
+		if (!this._manager) throw new ConnectionError("Monque not initialized. Call initialize() first.");
+		return this._manager;
+	}
+	/** @throws {ConnectionError} if not initialized */
+	get query() {
+		if (!this._query) throw new ConnectionError("Monque not initialized. Call initialize() first.");
+		return this._query;
+	}
+	/** @throws {ConnectionError} if not initialized */
+	get processor() {
+		if (!this._processor) throw new ConnectionError("Monque not initialized. Call initialize() first.");
+		return this._processor;
+	}
+	/** @throws {ConnectionError} if not initialized */
+	get changeStreamHandler() {
+		if (!this._changeStreamHandler) throw new ConnectionError("Monque not initialized. Call initialize() first.");
+		return this._changeStreamHandler;
+	}
+	/**
+	* Build the shared context for internal services.
+	*/
+	buildContext() {
+		if (!this.collection) throw new ConnectionError("Collection not initialized");
+		return {
+			collection: this.collection,
+			options: this.options,
+			instanceId: this.options.schedulerInstanceId,
+			workers: this.workers,
+			isRunning: () => this.isRunning,
+			emit: (event, payload) => this.emit(event, payload),
+			documentToPersistedJob: (doc) => this.documentToPersistedJob(doc)
+		};
+	}
+	/**
+	* Create required MongoDB indexes for efficient job processing.
+	*
+	* The following indexes are created:
+	* - `{status, nextRunAt}` - For efficient job polling queries
+	* - `{name, uniqueKey}` - Partial unique index for deduplication (pending/processing only)
+	* - `{name, status}` - For job lookup by type
+	* - `{claimedBy, status}` - For finding jobs owned by a specific scheduler instance
+	* - `{lastHeartbeat, status}` - For monitoring/debugging queries (e.g., inspecting heartbeat age)
+	* - `{status, nextRunAt, claimedBy}` - For atomic claim queries (find unclaimed pending jobs)
+	* - `{lockedAt, lastHeartbeat, status}` - Supports recovery scans and monitoring access patterns
+	*/
+	async createIndexes() {
+		if (!this.collection) throw new ConnectionError("Collection not initialized");
+		await this.collection.createIndex({
+			status: 1,
+			nextRunAt: 1
+		}, { background: true });
+		await this.collection.createIndex({
+			name: 1,
+			uniqueKey: 1
+		}, {
+			unique: true,
+			partialFilterExpression: {
+				uniqueKey: { $exists: true },
+				status: { $in: [JobStatus.PENDING, JobStatus.PROCESSING] }
+			},
+			background: true
+		});
+		await this.collection.createIndex({
+			name: 1,
+			status: 1
+		}, { background: true });
+		await this.collection.createIndex({
+			claimedBy: 1,
+			status: 1
+		}, { background: true });
+		await this.collection.createIndex({
+			lastHeartbeat: 1,
+			status: 1
+		}, { background: true });
+		await this.collection.createIndex({
+			status: 1,
+			nextRunAt: 1,
+			claimedBy: 1
+		}, { background: true });
+		await this.collection.createIndex({
+			status: 1,
+			lockedAt: 1,
+			lastHeartbeat: 1
+		}, { background: true });
+	}
+	/**
+	* Recover stale jobs that were left in 'processing' status.
+	* A job is considered stale if its `lockedAt` timestamp exceeds the configured `lockTimeout`.
+	* Stale jobs are reset to 'pending' so they can be picked up by workers again.
+	*/
+	async recoverStaleJobs() {
+		if (!this.collection) return;
+		const staleThreshold = new Date(Date.now() - this.options.lockTimeout);
+		const result = await this.collection.updateMany({
+			status: JobStatus.PROCESSING,
+			lockedAt: { $lt: staleThreshold }
+		}, {
+			$set: {
+				status: JobStatus.PENDING,
+				updatedAt: /* @__PURE__ */ new Date()
+			},
+			$unset: {
+				lockedAt: "",
+				claimedBy: "",
+				lastHeartbeat: "",
+				heartbeatInterval: ""
+			}
+		});
+		if (result.modifiedCount > 0) this.emit("stale:recovered", { count: result.modifiedCount });
+	}
+	/**
+	* 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() {
+		if (!this.collection || !this.options.jobRetention) return;
+		const { completed, failed } = this.options.jobRetention;
+		const now = Date.now();
+		const deletions = [];
+		if (completed) {
+			const cutoff = new Date(now - completed);
+			deletions.push(this.collection.deleteMany({
+				status: JobStatus.COMPLETED,
+				updatedAt: { $lt: cutoff }
+			}));
+		}
+		if (failed) {
+			const cutoff = new Date(now - failed);
+			deletions.push(this.collection.deleteMany({
+				status: JobStatus.FAILED,
+				updatedAt: { $lt: cutoff }
+			}));
+		}
+		if (deletions.length > 0) await Promise.all(deletions);
+	}
+	/**
+	* 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. This prevents duplicate scheduled jobs on application restart.
+	* 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 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
+	* @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 Hourly cleanup job
+	* @example Basic job enqueueing
 	* ```typescript
-	* await monque.schedule('0 * * * *', 'cleanup-temp-files', {
-	*   directory: '/tmp/uploads'
+	* await monque.enqueue('send-email', {
+	*   to: 'user@example.com',
+	*   subject: 'Welcome!',
+	*   body: 'Thanks for signing up.'
 	* });
 	* ```
 	*
-	* @example Prevent duplicate scheduled jobs with unique key
+	* @example Delayed execution
 	* ```typescript
-	* await monque.schedule('0 * * * *', 'hourly-report', { type: 'sales' }, {
-	*   uniqueKey: 'hourly-report-sales'
+	* const oneHourLater = new Date(Date.now() + 3600000);
+	* await monque.enqueue('reminder', { message: 'Check in!' }, {
+	*   runAt: oneHourLater
 	* });
-	* // Subsequent calls with same uniqueKey return existing pending/processing job
 	* ```
 	*
-	* @example Daily report at midnight (using predefined expression)
+	* @example Prevent duplicates with unique key
 	* ```typescript
-	* await monque.schedule('@daily', 'daily-report', {
-	*   reportType: 'sales',
-	*   recipients: ['analytics@example.com']
+	* await monque.enqueue('sync-user', { userId: '123' }, {
+	*   uniqueKey: 'sync-user-123'
 	* });
+	* // Subsequent enqueues with same uniqueKey return existing pending/processing job
 	* ```
 	*/
-	async schedule(cron, name, data, options = {}) {
+	async enqueue(name, data, options = {}) {
 		this.ensureInitialized();
-		const nextRunAt = getNextCronDate(cron);
-		const now = /* @__PURE__ */ new Date();
-		const job = {
-			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) {
-				if (!this.collection) throw new require_errors.ConnectionError("Failed to schedule job: collection not available");
-				const result$1 = await this.collection.findOneAndUpdate({
-					name,
-					uniqueKey: options.uniqueKey,
-					status: { $in: [JobStatus.PENDING, JobStatus.PROCESSING] }
-				}, { $setOnInsert: job }, {
-					upsert: true,
-					returnDocument: "after"
-				});
-				if (!result$1) throw new require_errors.ConnectionError("Failed to schedule job: findOneAndUpdate returned no document");
-				return this.documentToPersistedJob(result$1);
-			}
-			const result = await this.collection?.insertOne(job);
-			if (!result) throw new require_errors.ConnectionError("Failed to schedule job: collection not available");
-			return {
-				...job,
-				_id: result.insertedId
-			};
-		} catch (error) {
-			if (error instanceof require_errors.MonqueError) throw error;
-			throw new require_errors.ConnectionError(`Failed to schedule job: ${error instanceof Error ? error.message : "Unknown error during schedule"}`, error instanceof Error ? { cause: error } : void 0);
-		}
+		return this.scheduler.enqueue(name, data, options);
 	}
 	/**
-	* Register a worker to process jobs of a specific type.
-	*
-	* Workers can be registered before or after calling `start()`. Each worker
-	* processes jobs concurrently up to its configured concurrency limit (default: 5).
-	*
-	* The handler function receives the full job object including metadata (`_id`, `status`,
-	* `failCount`, etc.). If the handler throws an error, the job is retried with exponential
-	* backoff up to `maxRetries` times. After exhausting retries, the job is marked as `failed`.
+	* Enqueue a job for immediate processing.
 	*
-	* Events are emitted during job processing: `job:start`, `job:complete`, `job:fail`, and `job:error`.
+	* 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`).
 	*
-	* **Duplicate Registration**: By default, registering a worker for a job name that already has
-	* a worker will throw a `WorkerRegistrationError`. This fail-fast behavior prevents accidental
-	* replacement of handlers. To explicitly replace a worker, pass `{ replace: true }`.
+	* @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
 	*
-	* @template T - The job data payload type for type-safe access to `job.data`
-	* @param name - Job type identifier to handle
-	* @param handler - Async function to execute for each job
-	* @param options - Worker configuration
-	* @param options.concurrency - Maximum concurrent jobs for this worker (default: `defaultConcurrency`)
-	* @param options.replace - When `true`, replace existing worker instead of throwing error
-	* @throws {WorkerRegistrationError} When a worker is already registered for `name` and `replace` is not `true`
+	* @example Send email immediately
+	* ```typescript
+	* await monque.now('send-email', {
+	*   to: 'admin@example.com',
+	*   subject: 'Alert',
+	*   body: 'Immediate attention required'
+	* });
+	* ```
 	*
-	* @example Basic email worker
+	* @example Process order in background
 	* ```typescript
-	* interface EmailJob {
-	*   to: string;
-	*   subject: string;
-	*   body: string;
-	* }
+	* const order = await createOrder(data);
+	* await monque.now('process-order', { orderId: order.id });
+	* return order; // Return immediately, processing happens async
+	* ```
+	*/
+	async now(name, data) {
+		this.ensureInitialized();
+		return this.scheduler.now(name, data);
+	}
+	/**
+	* 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.
 	*
-	* monque.register<EmailJob>('send-email', async (job) => {
-	*   await emailService.send(job.data.to, job.data.subject, job.data.body);
-	* });
-	* ```
+	* When a `uniqueKey` is provided, only one pending or processing job with that key
+	* can exist. This prevents duplicate scheduled jobs on application restart.
 	*
-	* @example Worker with custom concurrency
+	* @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
-	* // Limit to 2 concurrent video processing jobs (resource-intensive)
-	* monque.register('process-video', async (job) => {
-	*   await videoProcessor.transcode(job.data.videoId);
-	* }, { concurrency: 2 });
+	* await monque.schedule('0 * * * *', 'cleanup-temp-files', {
+	*   directory: '/tmp/uploads'
+	* });
 	* ```
 	*
-	* @example Replacing an existing worker
+	* @example Prevent duplicate scheduled jobs with unique key
 	* ```typescript
-	* // Replace the existing handler for 'send-email'
-	* monque.register('send-email', newEmailHandler, { replace: true });
+	* await monque.schedule('0 * * * *', 'hourly-report', { type: 'sales' }, {
+	*   uniqueKey: 'hourly-report-sales'
+	* });
+	* // Subsequent calls with same uniqueKey return existing pending/processing job
 	* ```
 	*
-	* @example Worker with error handling
+	* @example Daily report at midnight (using predefined expression)
 	* ```typescript
-	* monque.register('sync-user', async (job) => {
-	*   try {
-	*     await externalApi.syncUser(job.data.userId);
-	*   } catch (error) {
-	*     // Job will retry with exponential backoff
-	*     // Delay = 2^failCount × baseRetryInterval (default: 1000ms)
-	*     throw new Error(`Sync failed: ${error.message}`);
-	*   }
+	* await monque.schedule('@daily', 'daily-report', {
+	*   reportType: 'sales',
+	*   recipients: ['analytics@example.com']
 	* });
 	* ```
 	*/
-	register(name, handler, options = {}) {
-		const concurrency = options.concurrency ?? this.options.defaultConcurrency;
-		if (this.workers.has(name) && options.replace !== true) throw new require_errors.WorkerRegistrationError(`Worker already registered for job name "${name}". Use { replace: true } to replace.`, name);
-		this.workers.set(name, {
-			handler,
-			concurrency,
-			activeJobs: /* @__PURE__ */ new Map()
-		});
+	async schedule(cron, name, data, options = {}) {
+		this.ensureInitialized();
+		return this.scheduler.schedule(cron, name, data, options);
 	}
 	/**
-	* Start polling for and processing jobs.
+	* Cancel a pending or scheduled job.
 	*
-	* Begins polling MongoDB at the configured interval (default: 1 second) to pick up
-	* pending jobs and dispatch them to registered workers. Must call `initialize()` first.
-	* Workers can be registered before or after calling `start()`.
+	* 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'.
 	*
-	* Jobs are processed concurrently up to each worker's configured concurrency limit.
-	* The scheduler continues running until `stop()` is called.
+	* @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 Basic startup
+	* @example Cancel a pending job
 	* ```typescript
-	* const monque = new Monque(db);
-	* await monque.initialize();
+	* const job = await monque.enqueue('report', { type: 'daily' });
+	* await monque.cancelJob(job._id.toString());
+	* ```
+	*/
+	async cancelJob(jobId) {
+		this.ensureInitialized();
+		return this.manager.cancelJob(jobId);
+	}
+	/**
+	* Retry a failed or cancelled job.
 	*
-	* monque.register('send-email', emailHandler);
-	* monque.register('process-order', orderHandler);
+	* Resets the job to 'pending' status, clears failure count/reason, and sets
+	* nextRunAt to now (immediate retry). Emits a 'job:retried' event.
 	*
-	* monque.start(); // Begin processing jobs
-	* ```
+	* @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 With event monitoring
+	* @example Retry a failed job
 	* ```typescript
-	* monque.on('job:start', (job) => {
-	*   logger.info(`Starting job ${job.name}`);
+	* monque.on('job:fail', async ({ job }) => {
+	*   console.log(`Job ${job._id} failed, retrying manually...`);
+	*   await monque.retryJob(job._id.toString());
 	* });
+	* ```
+	*/
+	async retryJob(jobId) {
+		this.ensureInitialized();
+		return this.manager.retryJob(jobId);
+	}
+	/**
+	* Reschedule a pending job to run at a different time.
 	*
-	* monque.on('job:complete', ({ job, duration }) => {
-	*   metrics.recordJobDuration(job.name, duration);
-	* });
+	* Only works for jobs in 'pending' status.
 	*
-	* monque.on('job:fail', ({ job, error, willRetry }) => {
-	*   logger.error(`Job ${job.name} failed:`, error);
-	*   if (!willRetry) {
-	*     alerting.sendAlert(`Job permanently failed: ${job.name}`);
-	*   }
-	* });
+	* @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
 	*
-	* monque.start();
+	* @example Delay a job by 1 hour
+	* ```typescript
+	* const nextHour = new Date(Date.now() + 60 * 60 * 1000);
+	* await monque.rescheduleJob(jobId, nextHour);
 	* ```
-	*
-	* @throws {ConnectionError} If scheduler not initialized (call `initialize()` first)
 	*/
-	start() {
-		if (this.isRunning) return;
-		if (!this.isInitialized) throw new require_errors.ConnectionError("Monque not initialized. Call initialize() before start().");
-		this.isRunning = true;
-		this.setupChangeStream();
-		this.pollIntervalId = setInterval(() => {
-			this.poll().catch((error) => {
-				this.emit("job:error", { error });
-			});
-		}, this.options.pollInterval);
-		this.heartbeatIntervalId = setInterval(() => {
-			this.updateHeartbeats().catch((error) => {
-				this.emit("job:error", { error });
-			});
-		}, this.options.heartbeatInterval);
-		if (this.options.jobRetention) {
-			const interval = this.options.jobRetention.interval ?? DEFAULTS.retentionInterval;
-			this.cleanupJobs().catch((error) => {
-				this.emit("job:error", { error });
-			});
-			this.cleanupIntervalId = setInterval(() => {
-				this.cleanupJobs().catch((error) => {
-					this.emit("job:error", { error });
-				});
-			}, interval);
-		}
-		this.poll().catch((error) => {
-			this.emit("job:error", { error });
-		});
+	async rescheduleJob(jobId, runAt) {
+		this.ensureInitialized();
+		return this.manager.rescheduleJob(jobId, runAt);
 	}
 	/**
-	* Stop the scheduler gracefully, waiting for in-progress jobs to complete.
+	* Permanently delete a job.
 	*
-	* Stops polling for new jobs and waits for all active jobs to finish processing.
-	* Times out after the configured `shutdownTimeout` (default: 30 seconds), emitting
-	* a `job:error` event with a `ShutdownTimeoutError` containing incomplete jobs.
-	* On timeout, jobs still in progress are left as `processing` for stale job recovery.
+	* This action is irreversible. Emits a 'job:deleted' event upon success.
+	* Can delete a job in any state.
 	*
-	* It's safe to call `stop()` multiple times - subsequent calls are no-ops if already stopped.
+	* @param jobId - The ID of the job to delete
+	* @returns true if deleted, false if job not found
 	*
-	* @returns Promise that resolves when all jobs complete or timeout is reached
+	* @example Delete a cleanup job
+	* ```typescript
+	* const deleted = await monque.deleteJob(jobId);
+	* if (deleted) {
+	*   console.log('Job permanently removed');
+	* }
+	* ```
+	*/
+	async deleteJob(jobId) {
+		this.ensureInitialized();
+		return this.manager.deleteJob(jobId);
+	}
+	/**
+	* Cancel multiple jobs matching the given filter.
 	*
-	* @example Graceful application shutdown
+	* 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
-	* process.on('SIGTERM', async () => {
-	*   console.log('Shutting down gracefully...');
-	*   await monque.stop(); // Wait for jobs to complete
-	*   await mongoClient.close();
-	*   process.exit(0);
+	* const result = await monque.cancelJobs({
+	*   name: 'email-queue',
+	*   status: 'pending'
 	* });
+	* console.log(`Cancelled ${result.count} jobs`);
 	* ```
+	*/
+	async cancelJobs(filter) {
+		this.ensureInitialized();
+		return this.manager.cancelJobs(filter);
+	}
+	/**
+	* Retry multiple jobs matching the given filter.
 	*
-	* @example With timeout handling
+	* 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
-	* monque.on('job:error', ({ error }) => {
-	*   if (error.name === 'ShutdownTimeoutError') {
-	*     logger.warn('Forced shutdown after timeout:', error.incompleteJobs);
-	*   }
+	* const result = await monque.retryJobs({
+	*   status: 'failed'
 	* });
-	*
-	* await monque.stop();
+	* console.log(`Retried ${result.count} jobs`);
 	* ```
 	*/
-	async stop() {
-		if (!this.isRunning) return;
-		this.isRunning = false;
-		await this.closeChangeStream();
-		if (this.changeStreamDebounceTimer) {
-			clearTimeout(this.changeStreamDebounceTimer);
-			this.changeStreamDebounceTimer = null;
-		}
-		if (this.changeStreamReconnectTimer) {
-			clearTimeout(this.changeStreamReconnectTimer);
-			this.changeStreamReconnectTimer = null;
-		}
-		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;
-		}
-		if (this.getActiveJobs().length === 0) return;
-		let checkInterval;
-		const waitForJobs = new Promise((resolve) => {
-			checkInterval = setInterval(() => {
-				if (this.getActiveJobs().length === 0) {
-					clearInterval(checkInterval);
-					resolve(void 0);
-				}
-			}, 100);
-		});
-		const timeout = new Promise((resolve) => {
-			setTimeout(() => resolve("timeout"), this.options.shutdownTimeout);
-		});
-		let result;
-		try {
-			result = await Promise.race([waitForJobs, timeout]);
-		} finally {
-			if (checkInterval) clearInterval(checkInterval);
-		}
-		if (result === "timeout") {
-			const incompleteJobs = this.getActiveJobsList();
-			const { ShutdownTimeoutError: ShutdownTimeoutError$1 } = await Promise.resolve().then(() => require("./errors-Dfli-u59.cjs"));
-			const error = new ShutdownTimeoutError$1(`Shutdown timed out after ${this.options.shutdownTimeout}ms with ${incompleteJobs.length} incomplete jobs`, incompleteJobs);
-			this.emit("job:error", { error });
-		}
+	async retryJobs(filter) {
+		this.ensureInitialized();
+		return this.manager.retryJobs(filter);
 	}
 	/**
-	* Check if the scheduler is healthy (running and connected).
-	*
-	* Returns `true` when the scheduler is started, initialized, and has an active
-	* MongoDB collection reference. Useful for health check endpoints and monitoring.
+	* Delete multiple jobs matching the given filter.
 	*
-	* A healthy scheduler:
-	* - Has called `initialize()` successfully
-	* - Has called `start()` and is actively polling
-	* - Has a valid MongoDB collection reference
+	* Deletes jobs in any status. Uses a batch delete for efficiency.
+	* Does not emit individual 'job:deleted' events to avoid noise.
 	*
-	* @returns `true` if scheduler is running and connected, `false` otherwise
+	* @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 Express health check endpoint
+	* @example Delete old completed jobs
 	* ```typescript
-	* app.get('/health', (req, res) => {
-	*   const healthy = monque.isHealthy();
-	*   res.status(healthy ? 200 : 503).json({
-	*     status: healthy ? 'ok' : 'unavailable',
-	*     scheduler: healthy,
-	*     timestamp: new Date().toISOString()
-	*   });
+	* 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) {
+		this.ensureInitialized();
+		return this.manager.deleteJobs(filter);
+	}
+	/**
+	* Get a single job by its MongoDB ObjectId.
 	*
-	* @example Kubernetes readiness probe
+	* Useful for retrieving job details when you have a job ID from events,
+	* logs, or stored references.
+	*
+	* @template T - The expected type of the job data payload
+	* @param id - The job's ObjectId
+	* @returns Promise resolving to the job if found, null otherwise
+	* @throws {ConnectionError} If scheduler not initialized
+	*
+	* @example Look up job from event
 	* ```typescript
-	* app.get('/readyz', (req, res) => {
-	*   if (monque.isHealthy() && dbConnected) {
-	*     res.status(200).send('ready');
-	*   } else {
-	*     res.status(503).send('not ready');
-	*   }
+	* monque.on('job:fail', async ({ job }) => {
+	*   // Later, retrieve the job to check its status
+	*   const currentJob = await monque.getJob(job._id);
+	*   console.log(`Job status: ${currentJob?.status}`);
 	* });
 	* ```
 	*
-	* @example Periodic health monitoring
+	* @example Admin endpoint
 	* ```typescript
-	* setInterval(() => {
-	*   if (!monque.isHealthy()) {
-	*     logger.error('Scheduler unhealthy');
-	*     metrics.increment('scheduler.unhealthy');
+	* app.get('/jobs/:id', async (req, res) => {
+	*   const job = await monque.getJob(new ObjectId(req.params.id));
+	*   if (!job) {
+	*     return res.status(404).json({ error: 'Job not found' });
 	*   }
-	* }, 60000); // Check every minute
+	*   res.json(job);
+	* });
 	* ```
-	*/
-	isHealthy() {
-		return this.isRunning && this.isInitialized && this.collection !== null;
+	*/
+	async getJob(id) {
+		this.ensureInitialized();
+		return this.query.getJob(id);
 	}
 	/**
 	* Query jobs from the queue with optional filters.
@@ -1135,398 +2450,345 @@ var Monque = class extends node_events.EventEmitter {
 	*/
 	async getJobs(filter = {}) {
 		this.ensureInitialized();
-		if (!this.collection) throw new require_errors.ConnectionError("Failed to query jobs: collection not available");
-		const query = {};
-		if (filter.name !== void 0) query["name"] = filter.name;
-		if (filter.status !== void 0) if (Array.isArray(filter.status)) query["status"] = { $in: filter.status };
-		else query["status"] = filter.status;
-		const limit = filter.limit ?? 100;
-		const skip = filter.skip ?? 0;
-		try {
-			return (await this.collection.find(query).sort({ nextRunAt: 1 }).skip(skip).limit(limit).toArray()).map((doc) => this.documentToPersistedJob(doc));
-		} catch (error) {
-			throw new require_errors.ConnectionError(`Failed to query jobs: ${error instanceof Error ? error.message : "Unknown error during getJobs"}`, error instanceof Error ? { cause: error } : void 0);
-		}
+		return this.query.getJobs(filter);
 	}
 	/**
-	* Get a single job by its MongoDB ObjectId.
+	* Get a paginated list of jobs using opaque cursors.
 	*
-	* Useful for retrieving job details when you have a job ID from events,
-	* logs, or stored references.
+	* Provides stable pagination for large job lists. Supports forward and backward
+	* navigation, filtering, and efficient database access via index-based cursor queries.
 	*
-	* @template T - The expected type of the job data payload
-	* @param id - The job's ObjectId
-	* @returns Promise resolving to the job if found, null otherwise
-	* @throws {ConnectionError} If scheduler not initialized
+	* @template T - The job data payload type
+	* @param options - Pagination options (cursor, limit, direction, filter)
+	* @returns Page of jobs with next/prev cursors
+	* @throws {InvalidCursorError} If the provided cursor is malformed
+	* @throws {ConnectionError} If database operation fails or scheduler not initialized
 	*
-	* @example Look up job from event
+	* @example List pending jobs
 	* ```typescript
-	* monque.on('job:fail', async ({ job }) => {
-	*   // Later, retrieve the job to check its status
-	*   const currentJob = await monque.getJob(job._id);
-	*   console.log(`Job status: ${currentJob?.status}`);
+	* const page = await monque.getJobsWithCursor({
+	*   limit: 20,
+	*   filter: { status: 'pending' }
 	* });
-	* ```
+	* const jobs = page.jobs;
 	*
-	* @example Admin endpoint
-	* ```typescript
-	* app.get('/jobs/:id', async (req, res) => {
-	*   const job = await monque.getJob(new ObjectId(req.params.id));
-	*   if (!job) {
-	*     return res.status(404).json({ error: 'Job not found' });
-	*   }
-	*   res.json(job);
-	* });
+	* // Get next page
+	* if (page.hasNextPage) {
+	*   const page2 = await monque.getJobsWithCursor({
+	*     cursor: page.cursor,
+	*     limit: 20
+	*   });
+	* }
 	* ```
 	*/
-	async getJob(id) {
+	async getJobsWithCursor(options = {}) {
 		this.ensureInitialized();
-		if (!this.collection) throw new require_errors.ConnectionError("Failed to get job: collection not available");
-		try {
-			const doc = await this.collection.findOne({ _id: id });
-			if (!doc) return null;
-			return this.documentToPersistedJob(doc);
-		} catch (error) {
-			throw new require_errors.ConnectionError(`Failed to get job: ${error instanceof Error ? error.message : "Unknown error during getJob"}`, error instanceof Error ? { cause: error } : void 0);
-		}
+		return this.query.getJobsWithCursor(options);
 	}
 	/**
-	* Poll for available jobs and process them.
-	*
-	* Called at regular intervals (configured by `pollInterval`). For each registered worker,
-	* attempts to acquire jobs up to the worker's available concurrency slots.
-	* Aborts early if the scheduler is stopping (`isRunning` is false).
+	* Get aggregate statistics for the job queue.
 	*
-	* @private
-	*/
-	async poll() {
-		if (!this.isRunning || !this.collection) return;
-		for (const [name, worker] of this.workers) {
-			const availableSlots = worker.concurrency - worker.activeJobs.size;
-			if (availableSlots <= 0) continue;
-			for (let i = 0; i < availableSlots; i++) {
-				if (!this.isRunning) return;
-				const job = await this.acquireJob(name);
-				if (job) this.processJob(job, worker).catch((error) => {
-					this.emit("job:error", {
-						error,
-						job
-					});
-				});
-				else break;
-			}
-		}
-	}
-	/**
-	* Atomically acquire a pending job for processing using the claimedBy pattern.
+	* Uses MongoDB aggregation pipeline for efficient server-side calculation.
+	* Returns counts per status and optional average processing duration for completed jobs.
 	*
-	* Uses MongoDB's `findOneAndUpdate` with atomic operations to ensure only one scheduler
-	* instance can claim a job. The query ensures the job is:
-	* - In pending status
-	* - Has nextRunAt <= now
-	* - Is not claimed by another instance (claimedBy is null/undefined)
+	* @param filter - Optional filter to scope statistics by job name
+	* @returns Promise resolving to queue statistics
+	* @throws {AggregationTimeoutError} If aggregation exceeds 30 second timeout
+	* @throws {ConnectionError} If database operation fails
 	*
-	* Returns `null` immediately if scheduler is stopping (`isRunning` is false).
+	* @example Get overall queue statistics
+	* ```typescript
+	* const stats = await monque.getQueueStats();
+	* console.log(`Pending: ${stats.pending}, Failed: ${stats.failed}`);
+	* ```
 	*
-	* @private
-	* @param name - The job type to acquire
-	* @returns The acquired job with updated status, claimedBy, and heartbeat info, or `null` if no jobs available
+	* @example Get statistics for a specific job type
+	* ```typescript
+	* const emailStats = await monque.getQueueStats({ name: 'send-email' });
+	* console.log(`${emailStats.total} email jobs in queue`);
+	* ```
 	*/
-	async acquireJob(name) {
-		if (!this.collection || !this.isRunning) return null;
-		const now = /* @__PURE__ */ new Date();
-		const result = await this.collection.findOneAndUpdate({
-			name,
-			status: JobStatus.PENDING,
-			nextRunAt: { $lte: now },
-			$or: [{ claimedBy: null }, { claimedBy: { $exists: false } }]
-		}, { $set: {
-			status: JobStatus.PROCESSING,
-			claimedBy: this.options.schedulerInstanceId,
-			lockedAt: now,
-			lastHeartbeat: now,
-			heartbeatInterval: this.options.heartbeatInterval,
-			updatedAt: now
-		} }, {
-			sort: { nextRunAt: 1 },
-			returnDocument: "after"
-		});
-		if (!result) return null;
-		return this.documentToPersistedJob(result);
+	async getQueueStats(filter) {
+		this.ensureInitialized();
+		return this.query.getQueueStats(filter);
 	}
 	/**
-	* Execute a job using its registered worker handler.
+	* Register a worker to process jobs of a specific type.
 	*
-	* Tracks the job as active during processing, emits lifecycle events, and handles
-	* both success and failure cases. On success, calls `completeJob()`. On failure,
-	* calls `failJob()` which implements exponential backoff retry logic.
+	* Workers can be registered before or after calling `start()`. Each worker
+	* processes jobs concurrently up to its configured concurrency limit (default: 5).
 	*
-	* @private
-	* @param job - The job to process
-	* @param worker - The worker registration containing the handler and active job tracking
-	*/
-	async processJob(job, worker) {
-		const jobId = job._id.toString();
-		worker.activeJobs.set(jobId, job);
-		const startTime = Date.now();
-		this.emit("job:start", job);
-		try {
-			await worker.handler(job);
-			const duration = Date.now() - startTime;
-			await this.completeJob(job);
-			this.emit("job:complete", {
-				job,
-				duration
-			});
-		} catch (error) {
-			const err = error instanceof Error ? error : new Error(String(error));
-			await this.failJob(job, err);
-			const willRetry = job.failCount + 1 < this.options.maxRetries;
-			this.emit("job:fail", {
-				job,
-				error: err,
-				willRetry
-			});
-		} finally {
-			worker.activeJobs.delete(jobId);
-		}
-	}
-	/**
-	* Mark a job as completed successfully.
+	* The handler function receives the full job object including metadata (`_id`, `status`,
+	* `failCount`, etc.). If the handler throws an error, the job is retried with exponential
+	* backoff up to `maxRetries` times. After exhausting retries, the job is marked as `failed`.
 	*
-	* For recurring jobs (with `repeatInterval`), schedules the next run based on the cron
-	* expression and resets `failCount` to 0. For one-time jobs, sets status to `completed`.
-	* Clears `lockedAt` and `failReason` fields in both cases.
+	* Events are emitted during job processing: `job:start`, `job:complete`, `job:fail`, and `job:error`.
 	*
-	* @private
-	* @param job - The job that completed successfully
-	*/
-	async completeJob(job) {
-		if (!this.collection || !isPersistedJob(job)) return;
-		if (job.repeatInterval) {
-			const nextRunAt = getNextCronDate(job.repeatInterval);
-			await this.collection.updateOne({ _id: job._id }, {
-				$set: {
-					status: JobStatus.PENDING,
-					nextRunAt,
-					failCount: 0,
-					updatedAt: /* @__PURE__ */ new Date()
-				},
-				$unset: {
-					lockedAt: "",
-					claimedBy: "",
-					lastHeartbeat: "",
-					heartbeatInterval: "",
-					failReason: ""
-				}
-			});
-		} else {
-			await this.collection.updateOne({ _id: job._id }, {
-				$set: {
-					status: JobStatus.COMPLETED,
-					updatedAt: /* @__PURE__ */ new Date()
-				},
-				$unset: {
-					lockedAt: "",
-					claimedBy: "",
-					lastHeartbeat: "",
-					heartbeatInterval: "",
-					failReason: ""
-				}
-			});
-			job.status = JobStatus.COMPLETED;
-		}
-	}
-	/**
-	* Handle job failure with exponential backoff retry logic.
+	* **Duplicate Registration**: By default, registering a worker for a job name that already has
+	* a worker will throw a `WorkerRegistrationError`. This fail-fast behavior prevents accidental
+	* replacement of handlers. To explicitly replace a worker, pass `{ replace: true }`.
 	*
-	* Increments `failCount` and calculates next retry time using exponential backoff:
-	* `nextRunAt = 2^failCount × baseRetryInterval` (capped by optional `maxBackoffDelay`).
+	* @template T - The job data payload type for type-safe access to `job.data`
+	* @param name - Job type identifier to handle
+	* @param handler - Async function to execute for each job
+	* @param options - Worker configuration
+	* @param options.concurrency - Maximum concurrent jobs for this worker (default: `defaultConcurrency`)
+	* @param options.replace - When `true`, replace existing worker instead of throwing error
+	* @throws {WorkerRegistrationError} When a worker is already registered for `name` and `replace` is not `true`
 	*
-	* If `failCount >= maxRetries`, marks job as permanently `failed`. Otherwise, resets
-	* to `pending` status for retry. Stores error message in `failReason` field.
+	* @example Basic email worker
+	* ```typescript
+	* interface EmailJob {
+	*   to: string;
+	*   subject: string;
+	*   body: string;
+	* }
 	*
-	* @private
-	* @param job - The job that failed
-	* @param error - The error that caused the failure
-	*/
-	async failJob(job, error) {
-		if (!this.collection || !isPersistedJob(job)) return;
-		const newFailCount = job.failCount + 1;
-		if (newFailCount >= this.options.maxRetries) await this.collection.updateOne({ _id: job._id }, {
-			$set: {
-				status: JobStatus.FAILED,
-				failCount: newFailCount,
-				failReason: error.message,
-				updatedAt: /* @__PURE__ */ new Date()
-			},
-			$unset: {
-				lockedAt: "",
-				claimedBy: "",
-				lastHeartbeat: "",
-				heartbeatInterval: ""
-			}
-		});
-		else {
-			const nextRunAt = calculateBackoff(newFailCount, this.options.baseRetryInterval, this.options.maxBackoffDelay);
-			await this.collection.updateOne({ _id: job._id }, {
-				$set: {
-					status: JobStatus.PENDING,
-					failCount: newFailCount,
-					failReason: error.message,
-					nextRunAt,
-					updatedAt: /* @__PURE__ */ new Date()
-				},
-				$unset: {
-					lockedAt: "",
-					claimedBy: "",
-					lastHeartbeat: "",
-					heartbeatInterval: ""
-				}
-			});
-		}
-	}
-	/**
-	* Ensure the scheduler is initialized before operations.
+	* monque.register<EmailJob>('send-email', async (job) => {
+	*   await emailService.send(job.data.to, job.data.subject, job.data.body);
+	* });
+	* ```
 	*
-	* @private
-	* @throws {ConnectionError} If scheduler not initialized or collection unavailable
+	* @example Worker with custom concurrency
+	* ```typescript
+	* // Limit to 2 concurrent video processing jobs (resource-intensive)
+	* monque.register('process-video', async (job) => {
+	*   await videoProcessor.transcode(job.data.videoId);
+	* }, { concurrency: 2 });
+	* ```
+	*
+	* @example Replacing an existing worker
+	* ```typescript
+	* // Replace the existing handler for 'send-email'
+	* monque.register('send-email', newEmailHandler, { replace: true });
+	* ```
+	*
+	* @example Worker with error handling
+	* ```typescript
+	* monque.register('sync-user', async (job) => {
+	*   try {
+	*     await externalApi.syncUser(job.data.userId);
+	*   } catch (error) {
+	*     // Job will retry with exponential backoff
+	*     // Delay = 2^failCount × baseRetryInterval (default: 1000ms)
+	*     throw new Error(`Sync failed: ${error.message}`);
+	*   }
+	* });
+	* ```
 	*/
-	ensureInitialized() {
-		if (!this.isInitialized || !this.collection) throw new require_errors.ConnectionError("Monque not initialized. Call initialize() first.");
+	register(name, handler, options = {}) {
+		const concurrency = options.concurrency ?? this.options.defaultConcurrency;
+		if (this.workers.has(name) && options.replace !== true) throw new WorkerRegistrationError(`Worker already registered for job name "${name}". Use { replace: true } to replace.`, name);
+		this.workers.set(name, {
+			handler,
+			concurrency,
+			activeJobs: /* @__PURE__ */ new Map()
+		});
 	}
 	/**
-	* Update heartbeats for all jobs claimed by this scheduler instance.
+	* Start polling for and processing jobs.
 	*
-	* This method runs periodically while the scheduler is running to indicate
-	* that jobs are still being actively processed.
+	* Begins polling MongoDB at the configured interval (default: 1 second) to pick up
+	* pending jobs and dispatch them to registered workers. Must call `initialize()` first.
+	* Workers can be registered before or after calling `start()`.
 	*
-	* `lastHeartbeat` is primarily an observability signal (monitoring/debugging).
-	* Stale recovery is based on `lockedAt` + `lockTimeout`.
+	* Jobs are processed concurrently up to each worker's configured concurrency limit.
+	* The scheduler continues running until `stop()` is called.
 	*
-	* @private
-	*/
-	async updateHeartbeats() {
-		if (!this.collection || !this.isRunning) return;
-		const now = /* @__PURE__ */ new Date();
-		await this.collection.updateMany({
-			claimedBy: this.options.schedulerInstanceId,
-			status: JobStatus.PROCESSING
-		}, { $set: {
-			lastHeartbeat: now,
-			updatedAt: now
-		} });
-	}
-	/**
-	* Set up MongoDB Change Stream for real-time job notifications.
+	* @example Basic startup
+	* ```typescript
+	* const monque = new Monque(db);
+	* await monque.initialize();
 	*
-	* 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.
+	* monque.register('send-email', emailHandler);
+	* monque.register('process-order', orderHandler);
 	*
-	* The change stream watches for:
-	* - Insert operations (new jobs)
-	* - Update operations where status field changes
+	* monque.start(); // Begin processing jobs
+	* ```
 	*
-	* If change streams are unavailable (e.g., standalone MongoDB), the system
-	* gracefully falls back to polling-only mode.
+	* @example With event monitoring
+	* ```typescript
+	* monque.on('job:start', (job) => {
+	*   logger.info(`Starting job ${job.name}`);
+	* });
 	*
-	* @private
+	* monque.on('job:complete', ({ job, duration }) => {
+	*   metrics.recordJobDuration(job.name, duration);
+	* });
+	*
+	* monque.on('job:fail', ({ job, error, willRetry }) => {
+	*   logger.error(`Job ${job.name} failed:`, error);
+	*   if (!willRetry) {
+	*     alerting.sendAlert(`Job permanently failed: ${job.name}`);
+	*   }
+	* });
+	*
+	* monque.start();
+	* ```
+	*
+	* @throws {ConnectionError} If scheduler not initialized (call `initialize()` first)
 	*/
-	setupChangeStream() {
-		if (!this.collection || !this.isRunning) return;
-		try {
-			this.changeStream = this.collection.watch([{ $match: { $or: [{ operationType: "insert" }, {
-				operationType: "update",
-				"updateDescription.updatedFields.status": { $exists: true }
-			}] } }], { fullDocument: "updateLookup" });
-			this.changeStream.on("change", (change) => {
-				this.handleChangeStreamEvent(change);
+	start() {
+		if (this.isRunning) return;
+		if (!this.isInitialized) throw new ConnectionError("Monque not initialized. Call initialize() before start().");
+		this.isRunning = true;
+		this.changeStreamHandler.setup();
+		this.pollIntervalId = setInterval(() => {
+			this.processor.poll().catch((error) => {
+				this.emit("job:error", { error });
 			});
-			this.changeStream.on("error", (error) => {
-				this.emit("changestream:error", { error });
-				this.handleChangeStreamError(error);
+		}, this.options.pollInterval);
+		this.heartbeatIntervalId = setInterval(() => {
+			this.processor.updateHeartbeats().catch((error) => {
+				this.emit("job:error", { error });
 			});
-			this.usingChangeStreams = true;
-			this.changeStreamReconnectAttempts = 0;
-			this.emit("changestream:connected", void 0);
-		} catch (error) {
-			this.usingChangeStreams = false;
-			const reason = error instanceof Error ? error.message : "Unknown error";
-			this.emit("changestream:fallback", { reason });
+		}, this.options.heartbeatInterval);
+		if (this.options.jobRetention) {
+			const interval = this.options.jobRetention.interval ?? DEFAULTS.retentionInterval;
+			this.cleanupJobs().catch((error) => {
+				this.emit("job:error", { error });
+			});
+			this.cleanupIntervalId = setInterval(() => {
+				this.cleanupJobs().catch((error) => {
+					this.emit("job:error", { error });
+				});
+			}, interval);
 		}
+		this.processor.poll().catch((error) => {
+			this.emit("job:error", { error });
+		});
 	}
 	/**
-	* Handle a change stream event by triggering a debounced poll.
+	* Stop the scheduler gracefully, waiting for in-progress jobs to complete.
 	*
-	* 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.
+	* Stops polling for new jobs and waits for all active jobs to finish processing.
+	* Times out after the configured `shutdownTimeout` (default: 30 seconds), emitting
+	* a `job:error` event with a `ShutdownTimeoutError` containing incomplete jobs.
+	* On timeout, jobs still in progress are left as `processing` for stale job recovery.
 	*
-	* @private
-	* @param change - The change stream event document
+	* It's safe to call `stop()` multiple times - subsequent calls are no-ops if already stopped.
+	*
+	* @returns Promise that resolves when all jobs complete or timeout is reached
+	*
+	* @example Graceful application shutdown
+	* ```typescript
+	* process.on('SIGTERM', async () => {
+	*   console.log('Shutting down gracefully...');
+	*   await monque.stop(); // Wait for jobs to complete
+	*   await mongoClient.close();
+	*   process.exit(0);
+	* });
+	* ```
+	*
+	* @example With timeout handling
+	* ```typescript
+	* monque.on('job:error', ({ error }) => {
+	*   if (error.name === 'ShutdownTimeoutError') {
+	*     logger.warn('Forced shutdown after timeout:', error.incompleteJobs);
+	*   }
+	* });
+	*
+	* await monque.stop();
+	* ```
 	*/
-	handleChangeStreamEvent(change) {
+	async stop() {
 		if (!this.isRunning) return;
-		const isInsert = change.operationType === "insert";
-		const isUpdate = change.operationType === "update";
-		const isPendingStatus = ("fullDocument" in change ? change.fullDocument : void 0)?.["status"] === JobStatus.PENDING;
-		if (isInsert || isUpdate && isPendingStatus) {
-			if (this.changeStreamDebounceTimer) clearTimeout(this.changeStreamDebounceTimer);
-			this.changeStreamDebounceTimer = setTimeout(() => {
-				this.changeStreamDebounceTimer = null;
-				this.poll().catch((error) => {
-					this.emit("job:error", { error });
-				});
+		this.isRunning = false;
+		await this.changeStreamHandler.close();
+		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;
+		}
+		if (this.getActiveJobs().length === 0) return;
+		let checkInterval;
+		const waitForJobs = new Promise((resolve) => {
+			checkInterval = setInterval(() => {
+				if (this.getActiveJobs().length === 0) {
+					clearInterval(checkInterval);
+					resolve(void 0);
+				}
 			}, 100);
+		});
+		const timeout = new Promise((resolve) => {
+			setTimeout(() => resolve("timeout"), this.options.shutdownTimeout);
+		});
+		let result;
+		try {
+			result = await Promise.race([waitForJobs, timeout]);
+		} finally {
+			if (checkInterval) clearInterval(checkInterval);
+		}
+		if (result === "timeout") {
+			const incompleteJobs = this.getActiveJobsList();
+			const error = new ShutdownTimeoutError(`Shutdown timed out after ${this.options.shutdownTimeout}ms with ${incompleteJobs.length} incomplete jobs`, incompleteJobs);
+			this.emit("job:error", { error });
 		}
 	}
 	/**
-	* Handle change stream errors with exponential backoff reconnection.
+	* Check if the scheduler is healthy (running and connected).
 	*
-	* Attempts to reconnect up to `maxChangeStreamReconnectAttempts` times with
-	* exponential backoff (base 1000ms). After exhausting retries, falls back to
-	* polling-only mode.
+	* Returns `true` when the scheduler is started, initialized, and has an active
+	* MongoDB collection reference. Useful for health check endpoints and monitoring.
 	*
-	* @private
-	* @param error - The error that caused the change stream failure
+	* A healthy scheduler:
+	* - Has called `initialize()` successfully
+	* - Has called `start()` and is actively polling
+	* - Has a valid MongoDB collection reference
+	*
+	* @returns `true` if scheduler is running and connected, `false` otherwise
+	*
+	* @example Express health check endpoint
+	* ```typescript
+	* app.get('/health', (req, res) => {
+	*   const healthy = monque.isHealthy();
+	*   res.status(healthy ? 200 : 503).json({
+	*     status: healthy ? 'ok' : 'unavailable',
+	*     scheduler: healthy,
+	*     timestamp: new Date().toISOString()
+	*   });
+	* });
+	* ```
+	*
+	* @example Kubernetes readiness probe
+	* ```typescript
+	* app.get('/readyz', (req, res) => {
+	*   if (monque.isHealthy() && dbConnected) {
+	*     res.status(200).send('ready');
+	*   } else {
+	*     res.status(503).send('not ready');
+	*   }
+	* });
+	* ```
+	*
+	* @example Periodic health monitoring
+	* ```typescript
+	* setInterval(() => {
+	*   if (!monque.isHealthy()) {
+	*     logger.error('Scheduler unhealthy');
+	*     metrics.increment('scheduler.unhealthy');
+	*   }
+	* }, 60000); // Check every minute
+	* ```
 	*/
-	handleChangeStreamError(error) {
-		if (!this.isRunning) return;
-		this.changeStreamReconnectAttempts++;
-		if (this.changeStreamReconnectAttempts > this.maxChangeStreamReconnectAttempts) {
-			this.usingChangeStreams = false;
-			this.emit("changestream:fallback", { reason: `Exhausted ${this.maxChangeStreamReconnectAttempts} reconnection attempts: ${error.message}` });
-			return;
-		}
-		const delay = 2 ** (this.changeStreamReconnectAttempts - 1) * 1e3;
-		if (this.changeStreamReconnectTimer) clearTimeout(this.changeStreamReconnectTimer);
-		this.changeStreamReconnectTimer = setTimeout(() => {
-			this.changeStreamReconnectTimer = null;
-			if (this.isRunning) {
-				if (this.changeStream) {
-					this.changeStream.close().catch(() => {});
-					this.changeStream = null;
-				}
-				this.setupChangeStream();
-			}
-		}, delay);
+	isHealthy() {
+		return this.isRunning && this.isInitialized && this.collection !== null;
 	}
 	/**
-	* Close the change stream cursor and emit closed event.
+	* Ensure the scheduler is initialized before operations.
 	*
 	* @private
+	* @throws {ConnectionError} If scheduler not initialized or collection unavailable
 	*/
-	async closeChangeStream() {
-		if (this.changeStream) {
-			try {
-				await this.changeStream.close();
-			} catch {}
-			this.changeStream = null;
-			if (this.usingChangeStreams) this.emit("changestream:closed", void 0);
-		}
-		this.usingChangeStreams = false;
-		this.changeStreamReconnectAttempts = 0;
+	ensureInitialized() {
+		if (!this.isInitialized || !this.collection) throw new ConnectionError("Monque not initialized. Call initialize() first.");
 	}
 	/**
 	* Get array of active job IDs across all workers.
@@ -1599,18 +2861,23 @@ var Monque = class extends node_events.EventEmitter {
 };
 
 //#endregion
-exports.ConnectionError = require_errors.ConnectionError;
+exports.AggregationTimeoutError = AggregationTimeoutError;
+exports.ConnectionError = ConnectionError;
+exports.CursorDirection = CursorDirection;
 exports.DEFAULT_BASE_INTERVAL = DEFAULT_BASE_INTERVAL;
 exports.DEFAULT_MAX_BACKOFF_DELAY = DEFAULT_MAX_BACKOFF_DELAY;
-exports.InvalidCronError = require_errors.InvalidCronError;
+exports.InvalidCronError = InvalidCronError;
+exports.InvalidCursorError = InvalidCursorError;
+exports.JobStateError = JobStateError;
 exports.JobStatus = JobStatus;
 exports.Monque = Monque;
-exports.MonqueError = require_errors.MonqueError;
-exports.ShutdownTimeoutError = require_errors.ShutdownTimeoutError;
-exports.WorkerRegistrationError = require_errors.WorkerRegistrationError;
+exports.MonqueError = MonqueError;
+exports.ShutdownTimeoutError = ShutdownTimeoutError;
+exports.WorkerRegistrationError = WorkerRegistrationError;
 exports.calculateBackoff = calculateBackoff;
 exports.calculateBackoffDelay = calculateBackoffDelay;
 exports.getNextCronDate = getNextCronDate;
+exports.isCancelledJob = isCancelledJob;
 exports.isCompletedJob = isCompletedJob;
 exports.isFailedJob = isFailedJob;
 exports.isPendingJob = isPendingJob;