@monque/core 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1618 @@
+const require_errors = require('./errors-BX3oWYfZ.cjs');
+let node_crypto = require("node:crypto");
+let node_events = require("node:events");
+let cron_parser = require("cron-parser");
+
+//#region src/jobs/types.ts
+/**
+* Represents the lifecycle states of a job in the queue.
+*
+* Jobs transition through states as follows:
+* - PENDING → PROCESSING (when picked up by a worker)
+* - PROCESSING → COMPLETED (on success)
+* - PROCESSING → PENDING (on failure, if retries remain)
+* - PROCESSING → FAILED (on failure, after max retries exhausted)
+*
+* @example
+* ```typescript
+* if (job.status === JobStatus.PENDING) {
+*   // job is waiting to be picked up
+* }
+* ```
+*/
+const JobStatus = {
+	PENDING: "pending",
+	PROCESSING: "processing",
+	COMPLETED: "completed",
+	FAILED: "failed"
+};
+
+//#endregion
+//#region src/jobs/guards.ts
+/**
+* Type guard to check if a job has been persisted to MongoDB.
+*
+* A persisted job is guaranteed to have an `_id` field, which means it has been
+* successfully inserted into the database. This is useful when you need to ensure
+* a job can be updated or referenced by its ID.
+*
+* @template T - The type of the job's data payload
+* @param job - The job to check
+* @returns `true` if the job has a valid `_id`, narrowing the type to `PersistedJob<T>`
+*
+* @example Basic usage
+* ```typescript
+* const job: Job<EmailData> = await monque.enqueue('send-email', emailData);
+*
+* if (isPersistedJob(job)) {
+*   // TypeScript knows job._id exists
+*   console.log(`Job ID: ${job._id.toString()}`);
+* }
+* ```
+*
+* @example In a conditional
+* ```typescript
+* function logJobId(job: Job) {
+*   if (!isPersistedJob(job)) {
+*     console.log('Job not yet persisted');
+*     return;
+*   }
+*   // TypeScript knows job is PersistedJob here
+*   console.log(`Processing job ${job._id.toString()}`);
+* }
+* ```
+*/
+function isPersistedJob(job) {
+	return "_id" in job && job._id !== void 0 && job._id !== null;
+}
+/**
+* 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
+* of user input or external data.
+*
+* @param value - The value to check
+* @returns `true` if the value is a valid `JobStatusType`, narrowing the type
+*
+* @example Validating user input
+* ```typescript
+* function filterByStatus(status: string) {
+*   if (!isValidJobStatus(status)) {
+*     throw new Error(`Invalid status: ${status}`);
+*   }
+*   // TypeScript knows status is JobStatusType here
+*   return db.jobs.find({ status });
+* }
+* ```
+*
+* @example Runtime validation
+* ```typescript
+* const statusFromApi = externalData.status;
+*
+* if (isValidJobStatus(statusFromApi)) {
+*   job.status = statusFromApi;
+* } else {
+*   job.status = JobStatus.PENDING;
+* }
+* ```
+*/
+function isValidJobStatus(value) {
+	return typeof value === "string" && Object.values(JobStatus).includes(value);
+}
+/**
+* Type guard to check if a job is in pending status.
+*
+* A convenience helper for checking if a job is waiting to be processed.
+* Equivalent to `job.status === JobStatus.PENDING` 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 `'pending'`
+*
+* @example Filter pending jobs
+* ```typescript
+* const jobs = await monque.getJobs();
+* const pendingJobs = jobs.filter(isPendingJob);
+* console.log(`${pendingJobs.length} jobs waiting to be processed`);
+* ```
+*
+* @example Conditional logic
+* ```typescript
+* if (isPendingJob(job)) {
+*   await monque.now(job.name, job.data);
+* }
+* ```
+*/
+function isPendingJob(job) {
+	return job.status === JobStatus.PENDING;
+}
+/**
+* Type guard to check if a job is currently being processed.
+*
+* A convenience helper for checking if a job is actively running.
+* Equivalent to `job.status === JobStatus.PROCESSING` 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 `'processing'`
+*
+* @example Monitor active jobs
+* ```typescript
+* const jobs = await monque.getJobs();
+* const activeJobs = jobs.filter(isProcessingJob);
+* console.log(`${activeJobs.length} jobs currently running`);
+* ```
+*/
+function isProcessingJob(job) {
+	return job.status === JobStatus.PROCESSING;
+}
+/**
+* Type guard to check if a job has completed successfully.
+*
+* A convenience helper for checking if a job finished without errors.
+* Equivalent to `job.status === JobStatus.COMPLETED` 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 `'completed'`
+*
+* @example Find completed jobs
+* ```typescript
+* const jobs = await monque.getJobs();
+* const completedJobs = jobs.filter(isCompletedJob);
+* console.log(`${completedJobs.length} jobs completed successfully`);
+* ```
+*/
+function isCompletedJob(job) {
+	return job.status === JobStatus.COMPLETED;
+}
+/**
+* Type guard to check if a job has permanently failed.
+*
+* A convenience helper for checking if a job exhausted all retries.
+* Equivalent to `job.status === JobStatus.FAILED` 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 `'failed'`
+*
+* @example Handle failed jobs
+* ```typescript
+* const jobs = await monque.getJobs();
+* const failedJobs = jobs.filter(isFailedJob);
+*
+* for (const job of failedJobs) {
+*   console.error(`Job ${job.name} failed: ${job.failReason}`);
+*   await sendAlert(job);
+* }
+* ```
+*/
+function isFailedJob(job) {
+	return job.status === JobStatus.FAILED;
+}
+/**
+* Type guard to check if a job is a recurring scheduled job.
+*
+* A recurring job has a `repeatInterval` cron expression and will be automatically
+* rescheduled after each successful completion.
+*
+* @template T - The type of the job's data payload
+* @param job - The job to check
+* @returns `true` if the job has a `repeatInterval` defined
+*
+* @example Filter recurring jobs
+* ```typescript
+* const jobs = await monque.getJobs();
+* const recurringJobs = jobs.filter(isRecurringJob);
+* console.log(`${recurringJobs.length} jobs will repeat automatically`);
+* ```
+*
+* @example Conditional cleanup
+* ```typescript
+* if (!isRecurringJob(job) && isCompletedJob(job)) {
+*   // Safe to delete one-time completed jobs
+*   await deleteJob(job._id);
+* }
+* ```
+*/
+function isRecurringJob(job) {
+	return job.repeatInterval !== void 0 && job.repeatInterval !== null;
+}
+
+//#endregion
+//#region src/shared/utils/backoff.ts
+/**
+* Default base interval for exponential backoff in milliseconds.
+* @default 1000
+*/
+const DEFAULT_BASE_INTERVAL = 1e3;
+/**
+* Default maximum delay cap for exponential backoff in milliseconds.
+*
+* This prevents unbounded delays (e.g. failCount=20 is >11 days at 1s base)
+* and avoids precision/overflow issues for very large fail counts.
+* @default 86400000 (24 hours)
+*/
+const DEFAULT_MAX_BACKOFF_DELAY = 1440 * 60 * 1e3;
+/**
+* Calculate the next run time using exponential backoff.
+*
+* Formula: nextRunAt = now + (2^failCount × baseInterval)
+*
+* @param failCount - Number of previous failed attempts
+* @param baseInterval - Base interval in milliseconds (default: 1000ms)
+* @param maxDelay - Maximum delay in milliseconds (optional)
+* @returns The next run date
+*
+* @example
+* ```typescript
+* // First retry (failCount=1): 2^1 * 1000 = 2000ms delay
+* const nextRun = calculateBackoff(1);
+*
+* // Second retry (failCount=2): 2^2 * 1000 = 4000ms delay
+* const nextRun = calculateBackoff(2);
+*
+* // With custom base interval
+* const nextRun = calculateBackoff(3, 500); // 2^3 * 500 = 4000ms delay
+*
+* // With max delay
+* const nextRun = calculateBackoff(10, 1000, 60000); // capped at 60000ms
+* ```
+*/
+function calculateBackoff(failCount, baseInterval = DEFAULT_BASE_INTERVAL, maxDelay) {
+	const effectiveMaxDelay = maxDelay ?? DEFAULT_MAX_BACKOFF_DELAY;
+	let delay = 2 ** failCount * baseInterval;
+	if (delay > effectiveMaxDelay) delay = effectiveMaxDelay;
+	return new Date(Date.now() + delay);
+}
+/**
+* Calculate just the delay in milliseconds for a given fail count.
+*
+* @param failCount - Number of previous failed attempts
+* @param baseInterval - Base interval in milliseconds (default: 1000ms)
+* @param maxDelay - Maximum delay in milliseconds (optional)
+* @returns The delay in milliseconds
+*/
+function calculateBackoffDelay(failCount, baseInterval = DEFAULT_BASE_INTERVAL, maxDelay) {
+	const effectiveMaxDelay = maxDelay ?? DEFAULT_MAX_BACKOFF_DELAY;
+	let delay = 2 ** failCount * baseInterval;
+	if (delay > effectiveMaxDelay) delay = effectiveMaxDelay;
+	return delay;
+}
+
+//#endregion
+//#region src/shared/utils/cron.ts
+/**
+* Parse a cron expression and return the next scheduled run date.
+*
+* @param expression - A 5-field cron expression (minute hour day-of-month month day-of-week) or a predefined expression
+* @param currentDate - The reference date for calculating next run (default: now)
+* @returns The next scheduled run date
+* @throws {InvalidCronError} If the cron expression is invalid
+*
+* @example
+* ```typescript
+* // Every minute
+* const nextRun = getNextCronDate('* * * * *');
+*
+* // Every day at midnight
+* const nextRun = getNextCronDate('0 0 * * *');
+*
+* // Using predefined expression
+* const nextRun = getNextCronDate('@daily');
+*
+* // Every Monday at 9am
+* const nextRun = getNextCronDate('0 9 * * 1');
+* ```
+*/
+function getNextCronDate(expression, currentDate) {
+	try {
+		return cron_parser.CronExpressionParser.parse(expression, { currentDate: currentDate ?? /* @__PURE__ */ new Date() }).next().toDate();
+	} catch (error) {
+		handleCronParseError(expression, error);
+	}
+}
+/**
+* Validate a cron expression without calculating the next run date.
+*
+* @param expression - A 5-field cron expression
+* @throws {InvalidCronError} If the cron expression is invalid
+*
+* @example
+* ```typescript
+* validateCronExpression('0 9 * * 1'); // Throws if invalid
+* ```
+*/
+function validateCronExpression(expression) {
+	try {
+		cron_parser.CronExpressionParser.parse(expression);
+	} catch (error) {
+		handleCronParseError(expression, error);
+	}
+}
+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)`);
+}
+
+//#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.worker<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.namecompleted in $durationms`);
+* });
+*
+* monque.on('job:fail', ({ job, error, willRetry }) => {
+*   logger.error(`Job $job.namefailed:`, 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;
+	/**
+	* MongoDB Change Stream for real-time job notifications.
+	* When available, provides instant job processing without polling delay.
+	*/
+	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.
+	*/
+	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
+		};
+	}
+	/**
+	* 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();
+			this.isInitialized = true;
+		} catch (error) {
+			throw new require_errors.ConnectionError(`Failed to initialize Monque: ${error instanceof Error ? error.message : "Unknown error during initialization"}`);
+		}
+	}
+	/**
+	* 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 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 });
+	}
+	/**
+	* 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. 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 = {}) {
+		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"
+				});
+				if (!result$1) throw new require_errors.ConnectionError("Failed to enqueue 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 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);
+		}
+	}
+	/**
+	* 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 = {}) {
+		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);
+		}
+	}
+	/**
+	* 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`.
+	*
+	* Events are emitted during job processing: `job:start`, `job:complete`, `job:fail`, and `job:error`.
+	*
+	* **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 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 Basic email worker
+	* ```typescript
+	* interface EmailJob {
+	*   to: string;
+	*   subject: string;
+	*   body: string;
+	* }
+	*
+	* monque.worker<EmailJob>('send-email', async (job) => {
+	*   await emailService.send(job.data.to, job.data.subject, job.data.body);
+	* });
+	* ```
+	*
+	* @example Worker with custom concurrency
+	* ```typescript
+	* // Limit to 2 concurrent video processing jobs (resource-intensive)
+	* monque.worker('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.worker('send-email', newEmailHandler, { replace: true });
+	* ```
+	*
+	* @example Worker with error handling
+	* ```typescript
+	* monque.worker('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}`);
+	*   }
+	* });
+	* ```
+	*/
+	worker(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()
+		});
+	}
+	/**
+	* Start polling for and processing jobs.
+	*
+	* 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()`.
+	*
+	* Jobs are processed concurrently up to each worker's configured concurrency limit.
+	* The scheduler continues running until `stop()` is called.
+	*
+	* @example Basic startup
+	* ```typescript
+	* const monque = new Monque(db);
+	* await monque.initialize();
+	*
+	* monque.worker('send-email', emailHandler);
+	* monque.worker('process-order', orderHandler);
+	*
+	* monque.start(); // Begin processing jobs
+	* ```
+	*
+	* @example With event monitoring
+	* ```typescript
+	* monque.on('job:start', (job) => {
+	*   logger.info(`Starting job ${job.name}`);
+	* });
+	*
+	* 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)
+	*/
+	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 });
+		});
+	}
+	/**
+	* Stop the scheduler gracefully, waiting for in-progress jobs to complete.
+	*
+	* 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.
+	*
+	* 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();
+	* ```
+	*/
+	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-Ca92IlaL.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 });
+		}
+	}
+	/**
+	* 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.
+	*
+	* 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
+	* ```
+	*/
+	isHealthy() {
+		return this.isRunning && this.isInitialized && this.collection !== null;
+	}
+	/**
+	* 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 = {}) {
+		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);
+		}
+	}
+	/**
+	* 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) {
+		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);
+		}
+	}
+	/**
+	* 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.
+	*
+	* @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++) {
+				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'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)
+	*
+	* @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
+	*/
+	async acquireJob(name) {
+		if (!this.collection) 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);
+	}
+	/**
+	* 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.
+	*
+	* @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.
+	*
+	* 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.
+	*
+	* @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.
+	*
+	* 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.
+	*
+	* @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.
+	*
+	* @private
+	* @throws {ConnectionError} If scheduler not initialized or collection unavailable
+	*/
+	ensureInitialized() {
+		if (!this.isInitialized || !this.collection) throw new require_errors.ConnectionError("Monque not initialized. Call initialize() first.");
+	}
+	/**
+	* 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`.
+	*
+	* @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.
+	*
+	* 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.
+	*
+	* @private
+	*/
+	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);
+			});
+			this.changeStream.on("error", (error) => {
+				this.emit("changestream:error", { error });
+				this.handleChangeStreamError(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 });
+		}
+	}
+	/**
+	* Handle a change stream event by triggering a debounced poll.
+	*
+	* Events are debounced to prevent "claim storms" when multiple changes arrive
+	* in rapid succession (e.g., bulk job inserts). A 100ms debounce window
+	* collects multiple events and triggers a single poll.
+	*
+	* @private
+	* @param change - The change stream event document
+	*/
+	handleChangeStreamEvent(change) {
+		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 });
+				});
+			}, 100);
+		}
+	}
+	/**
+	* Handle change stream errors with exponential backoff reconnection.
+	*
+	* Attempts to reconnect up to `maxChangeStreamReconnectAttempts` times with
+	* exponential backoff (base 1000ms). After exhausting retries, falls back to
+	* polling-only mode.
+	*
+	* @private
+	* @param error - The error that caused the change stream failure
+	*/
+	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);
+	}
+	/**
+	* Close the change stream cursor and emit closed event.
+	*
+	* @private
+	*/
+	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;
+	}
+	/**
+	* Get array of active job IDs across all workers.
+	*
+	* @private
+	* @returns Array of job ID strings currently being processed
+	*/
+	getActiveJobs() {
+		const activeJobs = [];
+		for (const worker of this.workers.values()) activeJobs.push(...worker.activeJobs.keys());
+		return activeJobs;
+	}
+	/**
+	* Get list of active job documents (for shutdown timeout error).
+	*
+	* @private
+	* @returns Array of active Job objects
+	*/
+	getActiveJobsList() {
+		const activeJobs = [];
+		for (const worker of this.workers.values()) activeJobs.push(...worker.activeJobs.values());
+		return activeJobs;
+	}
+	/**
+	* Convert a MongoDB document to a typed PersistedJob object.
+	*
+	* Maps raw MongoDB document fields to the strongly-typed `PersistedJob<T>` interface,
+	* ensuring type safety and handling optional fields (`lockedAt`, `failReason`, etc.).
+	*
+	* @private
+	* @template T - The job data payload type
+	* @param doc - The raw MongoDB document with `_id`
+	* @returns A strongly-typed PersistedJob object with guaranteed `_id`
+	*/
+	documentToPersistedJob(doc) {
+		const job = {
+			_id: doc._id,
+			name: doc["name"],
+			data: doc["data"],
+			status: doc["status"],
+			nextRunAt: doc["nextRunAt"],
+			failCount: doc["failCount"],
+			createdAt: doc["createdAt"],
+			updatedAt: doc["updatedAt"]
+		};
+		if (doc["lockedAt"] !== void 0) job.lockedAt = doc["lockedAt"];
+		if (doc["claimedBy"] !== void 0) job.claimedBy = doc["claimedBy"];
+		if (doc["lastHeartbeat"] !== void 0) job.lastHeartbeat = doc["lastHeartbeat"];
+		if (doc["heartbeatInterval"] !== void 0) job.heartbeatInterval = doc["heartbeatInterval"];
+		if (doc["failReason"] !== void 0) job.failReason = doc["failReason"];
+		if (doc["repeatInterval"] !== void 0) job.repeatInterval = doc["repeatInterval"];
+		if (doc["uniqueKey"] !== void 0) job.uniqueKey = doc["uniqueKey"];
+		return job;
+	}
+	/**
+	* Type-safe event emitter methods
+	*/
+	emit(event, payload) {
+		return super.emit(event, payload);
+	}
+	on(event, listener) {
+		return super.on(event, listener);
+	}
+	once(event, listener) {
+		return super.once(event, listener);
+	}
+	off(event, listener) {
+		return super.off(event, listener);
+	}
+};
+
+//#endregion
+exports.ConnectionError = require_errors.ConnectionError;
+exports.DEFAULT_BASE_INTERVAL = DEFAULT_BASE_INTERVAL;
+exports.DEFAULT_MAX_BACKOFF_DELAY = DEFAULT_MAX_BACKOFF_DELAY;
+exports.InvalidCronError = require_errors.InvalidCronError;
+exports.JobStatus = JobStatus;
+exports.Monque = Monque;
+exports.MonqueError = require_errors.MonqueError;
+exports.ShutdownTimeoutError = require_errors.ShutdownTimeoutError;
+exports.WorkerRegistrationError = require_errors.WorkerRegistrationError;
+exports.calculateBackoff = calculateBackoff;
+exports.calculateBackoffDelay = calculateBackoffDelay;
+exports.getNextCronDate = getNextCronDate;
+exports.isCompletedJob = isCompletedJob;
+exports.isFailedJob = isFailedJob;
+exports.isPendingJob = isPendingJob;
+exports.isPersistedJob = isPersistedJob;
+exports.isProcessingJob = isProcessingJob;
+exports.isRecurringJob = isRecurringJob;
+exports.isValidJobStatus = isValidJobStatus;
+exports.validateCronExpression = validateCronExpression;
+//# sourceMappingURL=index.cjs.map