@monque/core 1.0.0 → 1.1.1

package/dist/index.d.cts

@@ -2,7 +2,6 @@ import { Db, ObjectId } from "mongodb";
 import { EventEmitter } from "node:events";
 
 //#region src/jobs/types.d.ts
-
 /**
  * Represents the lifecycle states of a job in the queue.
  *
@@ -11,6 +10,7 @@ import { EventEmitter } from "node:events";
  * - 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
@@ -20,17 +20,14 @@ import { EventEmitter } from "node:events";
  * ```
  */
 declare const JobStatus: {
-  /** Job is waiting to be picked up by a worker */
-  readonly PENDING: "pending";
-  /** Job is currently being executed by a worker */
-  readonly PROCESSING: "processing";
-  /** Job completed successfully */
-  readonly COMPLETED: "completed";
-  /** Job permanently failed after exhausting all retry attempts */
-  readonly FAILED: "failed";
+  /** Job is waiting to be picked up by a worker */readonly PENDING: "pending"; /** Job is currently being executed by a worker */
+  readonly PROCESSING: "processing"; /** Job completed successfully */
+  readonly COMPLETED: "completed"; /** Job permanently failed after exhausting all retry attempts */
+  readonly FAILED: "failed"; /** Job was manually cancelled */
+  readonly CANCELLED: "cancelled";
 };
 /**
- * Union type of all possible job status values: `'pending' | 'processing' | 'completed' | 'failed'`
+ * Union type of all possible job status values: `'pending' | 'processing' | 'completed' | 'failed' | 'cancelled'`
  */
 type JobStatusType = (typeof JobStatus)[keyof typeof JobStatus];
 /**
@@ -192,6 +189,120 @@ interface GetJobsFilter {
  * ```
  */
 type JobHandler<T = unknown> = (job: Job<T>) => Promise<void> | void;
+/**
+ * Valid cursor directions for pagination.
+ *
+ * @example
+ * ```typescript
+ * const direction = CursorDirection.FORWARD;
+ * ```
+ */
+declare const CursorDirection: {
+  readonly FORWARD: "forward";
+  readonly BACKWARD: "backward";
+};
+type CursorDirectionType = (typeof CursorDirection)[keyof typeof CursorDirection];
+/**
+ * Selector options for bulk operations.
+ *
+ * Used to select multiple jobs for operations like cancellation or deletion.
+ *
+ * @example
+ * ```typescript
+ * // Select all failed jobs older than 7 days
+ * const selector: JobSelector = {
+ *   status: JobStatus.FAILED,
+ *   olderThan: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+ * };
+ * ```
+ */
+interface JobSelector {
+  name?: string;
+  status?: JobStatusType | JobStatusType[];
+  olderThan?: Date;
+  newerThan?: Date;
+}
+/**
+ * Options for cursor-based pagination.
+ *
+ * @example
+ * ```typescript
+ * const options: CursorOptions = {
+ *   limit: 50,
+ *   direction: CursorDirection.FORWARD,
+ *   filter: { status: JobStatus.PENDING },
+ * };
+ * ```
+ */
+interface CursorOptions {
+  cursor?: string;
+  limit?: number;
+  direction?: CursorDirectionType;
+  filter?: Pick<GetJobsFilter, 'name' | 'status'>;
+}
+/**
+ * Response structure for cursor-based pagination.
+ *
+ * @template T - The type of the job's data payload
+ *
+ * @example
+ * ```typescript
+ * const page = await monque.listJobs({ limit: 10 });
+ * console.log(`Got ${page.jobs.length} jobs`);
+ *
+ * if (page.hasNextPage) {
+ *   console.log(`Next cursor: ${page.cursor}`);
+ * }
+ * ```
+ */
+interface CursorPage<T = unknown> {
+  jobs: PersistedJob<T>[];
+  cursor: string | null;
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+}
+/**
+ * Aggregated statistics for the job queue.
+ *
+ * @example
+ * ```typescript
+ * const stats = await monque.getQueueStats();
+ * console.log(`Total jobs: ${stats.total}`);
+ * console.log(`Pending: ${stats.pending}`);
+ * console.log(`Processing: ${stats.processing}`);
+ * console.log(`Failed: ${stats.failed}`);
+ * console.log(`Start to finish avg: ${stats.avgProcessingDurationMs}ms`);
+ * ```
+ */
+interface QueueStats {
+  pending: number;
+  processing: number;
+  completed: number;
+  failed: number;
+  cancelled: number;
+  total: number;
+  avgProcessingDurationMs?: number;
+}
+/**
+ * Result of a bulk operation.
+ *
+ * @example
+ * ```typescript
+ * const result = await monque.cancelJobs(selector);
+ * console.log(`Cancelled ${result.count} jobs`);
+ *
+ * if (result.errors.length > 0) {
+ *   console.warn('Some jobs could not be cancelled:', result.errors);
+ * }
+ * ```
+ */
+interface BulkOperationResult {
+  count: number;
+  errors: Array<{
+    jobId: string;
+    error: string;
+  }>;
+}
 //#endregion
 //#region src/jobs/guards.d.ts
 /**
@@ -231,8 +342,8 @@ declare function isPersistedJob<T>(job: Job<T>): job is PersistedJob<T>;
 /**
  * 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
@@ -344,6 +455,24 @@ declare function isCompletedJob<T>(job: Job<T>): boolean;
  * ```
  */
 declare function isFailedJob<T>(job: Job<T>): boolean;
+/**
+ * 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`);
+ * ```
+ */
+declare function isCancelledJob<T>(job: Job<T>): boolean;
 /**
  * Type guard to check if a job is a recurring scheduled job.
  *
@@ -384,8 +513,7 @@ interface MonqueEventMap {
    * Emitted when a job finishes successfully.
    */
   'job:complete': {
-    job: Job;
-    /** Processing duration in milliseconds */
+    job: Job; /** Processing duration in milliseconds */
     duration: number;
   };
   /**
@@ -393,8 +521,7 @@ interface MonqueEventMap {
    */
   'job:fail': {
     job: Job;
-    error: Error;
-    /** Whether the job will be retried */
+    error: Error; /** Whether the job will be retried */
     willRetry: boolean;
   };
   /**
@@ -430,6 +557,45 @@ interface MonqueEventMap {
   'changestream:fallback': {
     reason: string;
   };
+  /**
+   * Emitted when a job is manually cancelled.
+   */
+  'job:cancelled': {
+    job: Job;
+  };
+  /**
+   * Emitted when a job is manually retried.
+   */
+  'job:retried': {
+    job: Job;
+    previousStatus: 'failed' | 'cancelled';
+  };
+  /**
+   * Emitted when a job is manually deleted.
+   */
+  'job:deleted': {
+    jobId: string;
+  };
+  /**
+   * Emitted when multiple jobs are cancelled in bulk.
+   */
+  'jobs:cancelled': {
+    jobIds: string[];
+    count: number;
+  };
+  /**
+   * Emitted when multiple jobs are retried in bulk.
+   */
+  'jobs:retried': {
+    jobIds: string[];
+    count: number;
+  };
+  /**
+   * Emitted when multiple jobs are deleted in bulk.
+   */
+  'jobs:deleted': {
+    count: number;
+  };
 }
 //#endregion
 //#region src/workers/types.d.ts
@@ -575,62 +741,43 @@ interface MonqueOptions {
  * stale job recovery, and event-driven observability. Built on native MongoDB driver.
  *
  * @example Complete lifecycle
- * ```;
-typescript
+ * ```typescript
+ * import { Monque } from '@monque/core';
+ * import { MongoClient } from 'mongodb';
  *
-
-import { Monque } from '@monque/core';
-
-*
-
-import { MongoClient } from 'mongodb';
-
-*
+ * const client = new MongoClient('mongodb://localhost:27017');
+ * await client.connect();
+ * const db = client.db('myapp');
  *
-const client = new MongoClient('mongodb://localhost:27017');
-* await client.connect()
-*
-const db = client.db('myapp');
-*
  * // Create instance with options
- *
-const monque = new Monque(db, {
+ * const monque = new Monque(db, {
  *   collectionName: 'jobs',
  *   pollInterval: 1000,
  *   maxRetries: 10,
  *   shutdownTimeout: 30000,
  * });
-*
+ *
  * // Initialize (sets up indexes and recovers stale jobs)
- * await monque.initialize()
-*
+ * await monque.initialize();
+ *
  * // Register workers with type safety
+ * type EmailJob = {
+ *   to: string;
+ *   subject: string;
+ *   body: string;
+ * };
  *
-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);
+ * });
  *
- * 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.namecompleted in $durationms`);
+ * 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.namefailed:`, error);
+ *   logger.error(`Job ${job.name} failed:`, error);
  * });
  *
  * // Start processing
@@ -661,34 +808,11 @@ declare class Monque extends EventEmitter {
   private cleanupIntervalId;
   private isRunning;
   private isInitialized;
-  /**
-   * MongoDB Change Stream for real-time job notifications.
-   * When available, provides instant job processing without polling delay.
-   */
-  private changeStream;
-  /**
-   * Number of consecutive reconnection attempts for change stream.
-   * Used for exponential backoff during reconnection.
-   */
-  private changeStreamReconnectAttempts;
-  /**
-   * Maximum reconnection attempts before falling back to polling-only mode.
-   */
-  private readonly maxChangeStreamReconnectAttempts;
-  /**
-   * Debounce timer for change stream event processing.
-   * Prevents claim storms when multiple events arrive in quick succession.
-   */
-  private changeStreamDebounceTimer;
-  /**
-   * Whether the scheduler is currently using change streams for notifications.
-   */
-  private usingChangeStreams;
-  /**
-   * Timer ID for change stream reconnection with exponential backoff.
-   * Tracked to allow cancellation during shutdown.
-   */
-  private changeStreamReconnectTimer;
+  private _scheduler;
+  private _manager;
+  private _query;
+  private _processor;
+  private _changeStreamHandler;
   constructor(db: Db, options?: MonqueOptions);
   /**
    * Initialize the scheduler by setting up the MongoDB collection and indexes.
@@ -697,6 +821,20 @@ declare class Monque extends EventEmitter {
    * @throws {ConnectionError} If collection or index creation fails
    */
   initialize(): Promise<void>;
+  /** @throws {ConnectionError} if not initialized */
+  private get scheduler();
+  /** @throws {ConnectionError} if not initialized */
+  private get manager();
+  /** @throws {ConnectionError} if not initialized */
+  private get query();
+  /** @throws {ConnectionError} if not initialized */
+  private get processor();
+  /** @throws {ConnectionError} if not initialized */
+  private get changeStreamHandler();
+  /**
+   * Build the shared context for internal services.
+   */
+  private buildContext;
   /**
    * Create required MongoDB indexes for efficient job processing.
    *
@@ -846,6 +984,266 @@ declare class Monque extends EventEmitter {
    * ```
    */
   schedule<T>(cron: string, name: string, data: T, options?: ScheduleOptions): Promise<PersistedJob<T>>;
+  /**
+   * 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());
+   * ```
+   */
+  cancelJob(jobId: string): Promise<PersistedJob<unknown> | null>;
+  /**
+   * 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());
+   * });
+   * ```
+   */
+  retryJob(jobId: string): Promise<PersistedJob<unknown> | null>;
+  /**
+   * Reschedule a pending job to run at a different time.
+   *
+   * Only works for jobs in 'pending' status.
+   *
+   * @param jobId - The ID of the job to reschedule
+   * @param runAt - The new Date when the job should run
+   * @returns The updated job, or null if not found
+   * @throws {JobStateError} If job is not in pending state
+   *
+   * @example Delay a job by 1 hour
+   * ```typescript
+   * const nextHour = new Date(Date.now() + 60 * 60 * 1000);
+   * await monque.rescheduleJob(jobId, nextHour);
+   * ```
+   */
+  rescheduleJob(jobId: string, runAt: Date): Promise<PersistedJob<unknown> | null>;
+  /**
+   * Permanently delete a job.
+   *
+   * This action is irreversible. Emits a 'job:deleted' event upon success.
+   * Can delete a job in any state.
+   *
+   * @param jobId - The ID of the job to delete
+   * @returns true if deleted, false if job not found
+   *
+   * @example Delete a cleanup job
+   * ```typescript
+   * const deleted = await monque.deleteJob(jobId);
+   * if (deleted) {
+   *   console.log('Job permanently removed');
+   * }
+   * ```
+   */
+  deleteJob(jobId: string): Promise<boolean>;
+  /**
+   * Cancel multiple jobs matching the given filter.
+   *
+   * Only cancels jobs in 'pending' status. Jobs in other states are collected
+   * as errors in the result. Emits a 'jobs:cancelled' event with the IDs of
+   * successfully cancelled jobs.
+   *
+   * @param filter - Selector for which jobs to cancel (name, status, date range)
+   * @returns Result with count of cancelled jobs and any errors encountered
+   *
+   * @example Cancel all pending jobs for a queue
+   * ```typescript
+   * const result = await monque.cancelJobs({
+   *   name: 'email-queue',
+   *   status: 'pending'
+   * });
+   * console.log(`Cancelled ${result.count} jobs`);
+   * ```
+   */
+  cancelJobs(filter: JobSelector): Promise<BulkOperationResult>;
+  /**
+   * Retry multiple jobs matching the given filter.
+   *
+   * Only retries jobs in 'failed' or 'cancelled' status. Jobs in other states
+   * are collected as errors in the result. Emits a 'jobs:retried' event with
+   * the IDs of successfully retried jobs.
+   *
+   * @param filter - Selector for which jobs to retry (name, status, date range)
+   * @returns Result with count of retried jobs and any errors encountered
+   *
+   * @example Retry all failed jobs
+   * ```typescript
+   * const result = await monque.retryJobs({
+   *   status: 'failed'
+   * });
+   * console.log(`Retried ${result.count} jobs`);
+   * ```
+   */
+  retryJobs(filter: JobSelector): Promise<BulkOperationResult>;
+  /**
+   * Delete multiple jobs matching the given filter.
+   *
+   * Deletes jobs in any status. Uses a batch delete for efficiency.
+   * 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`);
+   * ```
+   */
+  deleteJobs(filter: JobSelector): Promise<BulkOperationResult>;
+  /**
+   * 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);
+   * });
+   * ```
+   */
+  getJob<T = unknown>(id: ObjectId): Promise<PersistedJob<T> | 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));
+   * ```
+   */
+  getJobs<T = unknown>(filter?: GetJobsFilter): Promise<PersistedJob<T>[]>;
+  /**
+   * 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
+   *   });
+   * }
+   * ```
+   */
+  getJobsWithCursor<T = unknown>(options?: CursorOptions): Promise<CursorPage<T>>;
+  /**
+   * 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`);
+   * ```
+   */
+  getQueueStats(filter?: Pick<JobSelector, 'name'>): Promise<QueueStats>;
   /**
    * Register a worker to process jobs of a specific type.
    *
@@ -1036,144 +1434,6 @@ declare class Monque extends EventEmitter {
    * ```
    */
   isHealthy(): boolean;
-  /**
-   * 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));
-   * ```
-   */
-  getJobs<T = unknown>(filter?: GetJobsFilter): Promise<PersistedJob<T>[]>;
-  /**
-   * 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);
-   * });
-   * ```
-   */
-  getJob<T = unknown>(id: ObjectId): Promise<PersistedJob<T> | null>;
-  /**
-   * 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).
-   *
-   * @private
-   */
-  private poll;
-  /**
-   * 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).
-   *
-   * @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
-   */
-  private acquireJob;
-  /**
-   * 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
-   */
-  private processJob;
-  /**
-   * 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
-   */
-  private completeJob;
-  /**
-   * 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
-   */
-  private failJob;
   /**
    * Ensure the scheduler is initialized before operations.
    *
@@ -1181,63 +1441,6 @@ declare class Monque extends EventEmitter {
    * @throws {ConnectionError} If scheduler not initialized or collection unavailable
    */
   private ensureInitialized;
-  /**
-   * 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
-   */
-  private updateHeartbeats;
-  /**
-   * 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
-   */
-  private setupChangeStream;
-  /**
-   * 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
-   */
-  private handleChangeStreamEvent;
-  /**
-   * 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
-   */
-  private handleChangeStreamError;
-  /**
-   * Close the change stream cursor and emit closed event.
-   *
-   * @private
-   */
-  private closeChangeStream;
   /**
    * Get array of active job IDs across all workers.
    *
@@ -1370,6 +1573,60 @@ declare class WorkerRegistrationError extends MonqueError {
   readonly jobName: string;
   constructor(message: string, jobName: string);
 }
+/**
+ * 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}`);
+ *   }
+ * }
+ * ```
+ */
+declare class JobStateError extends MonqueError {
+  readonly jobId: string;
+  readonly currentStatus: string;
+  readonly attemptedAction: 'cancel' | 'retry' | 'reschedule';
+  constructor(message: string, jobId: string, currentStatus: string, attemptedAction: 'cancel' | 'retry' | 'reschedule');
+}
+/**
+ * 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');
+ *   }
+ * }
+ * ```
+ */
+declare class InvalidCursorError extends MonqueError {
+  constructor(message: string);
+}
+/**
+ * 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');
+ *   }
+ * }
+ * ```
+ */
+declare class AggregationTimeoutError extends MonqueError {
+  constructor(message?: string);
+}
 //#endregion
 //#region src/shared/utils/backoff.d.ts
 /**
@@ -1459,5 +1716,5 @@ declare function getNextCronDate(expression: string, currentDate?: Date): Date;
  */
 declare function validateCronExpression(expression: string): void;
 //#endregion
-export { ConnectionError, DEFAULT_BASE_INTERVAL, DEFAULT_MAX_BACKOFF_DELAY, type EnqueueOptions, type GetJobsFilter, InvalidCronError, type Job, type JobHandler, JobStatus, type JobStatusType, Monque, MonqueError, type MonqueEventMap, type MonqueOptions, type PersistedJob, type ScheduleOptions, ShutdownTimeoutError, type WorkerOptions, WorkerRegistrationError, calculateBackoff, calculateBackoffDelay, getNextCronDate, isCompletedJob, isFailedJob, isPendingJob, isPersistedJob, isProcessingJob, isRecurringJob, isValidJobStatus, validateCronExpression };
+export { AggregationTimeoutError, type BulkOperationResult, ConnectionError, CursorDirection, type CursorOptions, type CursorPage, DEFAULT_BASE_INTERVAL, DEFAULT_MAX_BACKOFF_DELAY, type EnqueueOptions, type GetJobsFilter, InvalidCronError, InvalidCursorError, type Job, type JobHandler, type JobSelector, JobStateError, JobStatus, type JobStatusType, Monque, MonqueError, type MonqueEventMap, type MonqueOptions, type PersistedJob, type QueueStats, type ScheduleOptions, ShutdownTimeoutError, type WorkerOptions, WorkerRegistrationError, calculateBackoff, calculateBackoffDelay, getNextCronDate, isCancelledJob, isCompletedJob, isFailedJob, isPendingJob, isPersistedJob, isProcessingJob, isRecurringJob, isValidJobStatus, validateCronExpression };
 //# sourceMappingURL=index.d.cts.map