@vorsteh-queue/core
Version:
Core queue engine for Vorsteh Queue with TypeScript support, job scheduling, and event system
290 lines (289 loc) • 9.31 kB
TypeScript
import type { BaseJob, JobHandler, JobOptions, QueueAdapter, QueueConfig, QueueEvents, QueueStats } from "../../types";
type EventListener<TEventData> = (data: TEventData) => void | Promise<void>;
/**
* Main queue class for managing job processing.
*
* @example
* ```typescript
* const queue = new Queue(adapter, { name: "my-queue" })
* queue.register("send-email", async (payload) => { ... })
* await queue.add("send-email", { to: "user@example.com" })
* queue.start()
* ```
*/
export declare class Queue {
private readonly adapter;
private readonly config;
private readonly handlers;
private readonly listeners;
private isRunning;
private isPaused;
private activeJobs;
private stopped;
constructor(adapter: QueueAdapter, config: QueueConfig);
connect(): Promise<void>;
disconnect(): Promise<void>;
/**
* Register a job handler for a specific job type.
*
* @param name The job type name
* @param handler Function to process jobs of this type
*
* @example
* ```typescript
* queue.register("send-email", async (payload: { to: string }) => {
* // Send email logic
* return { sent: true }
* })
* ```
*/
register<TJobPayload, TJobResult>(name: string, handler: JobHandler<TJobPayload, TJobResult>): void;
/**
* Add a new job to the queue.
*
* @param name The job type name (must be registered)
* @param payload Job data to process
* @param options Job configuration options
* @returns Promise resolving to the created job
*
* @example
* ```typescript
* // Basic job
* await queue.add("send-email", { to: "user@example.com" })
*
* // High priority job with delay
* await queue.add("urgent-task", { data: "important" }, {
* priority: 1,
* delay: 5000
* })
*
* // Recurring job
* await queue.add("cleanup", {}, {
* cron: "0 2 * * *" // Daily at 2 AM
* })
* ```
*/
add<TJobPayload>(name: string, payload: TJobPayload, options?: JobOptions): Promise<BaseJob<TJobPayload>>;
/**
* Alias for the `add()` method. Add a new job to the queue.
*
* @param name The job type name (must be registered)
* @param payload Job data to process
* @param options Job configuration options
* @returns Promise resolving to the created job
*
* @example
* ```typescript
* // Basic job
* await queue.enqueue("send-email", { to: "user@example.com" })
*
* // Priority job
* await queue.enqueue("urgent-task", { data: "important" }, { priority: 1 })
* ```
*/
enqueue<TJobPayload>(name: string, payload: TJobPayload, options?: JobOptions): Promise<BaseJob<TJobPayload>>;
/**
* Start processing jobs from the queue.
* Jobs will be processed according to priority and concurrency settings.
*/
start(): void;
/**
* Stop the queue and wait for active jobs to complete.
* Provides graceful shutdown functionality.
*/
stop(): Promise<void>;
/**
* Pause job processing. Jobs can still be added but won't be processed.
*/
pause(): void;
/**
* Resume job processing after being paused.
*/
resume(): void;
/**
* Get current queue statistics.
*
* @returns Promise<QueueStats> resolving to queue statistics
*
* @example
* ```typescript
* const stats = await queue.getStats()
* console.log(`Pending: ${stats.pending}, Processing: ${stats.processing}`)
* ```
*/
getStats(): Promise<QueueStats>;
/**
* Get current queue configuration.
*
* @returns Queue configuration object
*
* @example
* ```typescript
* const config = queue.getConfig()
* console.log(`Queue: ${config.name}, Concurrency: ${config.concurrency}`)
* ```
*/
getConfig(): Required<QueueConfig>;
/**
* Clear jobs from the queue.
*
* @param status Optional job status filter to clear only jobs with specific status
* @returns Promise<number> resolving to number of jobs cleared
*
* @example
* ```typescript
* // Clear all jobs
* const cleared = await queue.clear()
*
* // Clear only failed jobs
* const clearedFailed = await queue.clear("failed")
* ```
*/
clear(status?: Parameters<QueueAdapter["clearJobs"]>[0]): Promise<number>;
/**
* Update the progress of a specific job.
*
* @param id The job ID to update progress for
* @param progress Progress percentage (0-100)
* @returns Promise that resolves when progress is updated
*
* @example
* ```typescript
* // Update job progress to 50%
* await queue.updateJobProgress(jobId, 50)
*
* // Update job progress to completion
* await queue.updateJobProgress(jobId, 100)
* ```
*/
updateJobProgress(id: string, progress: number): Promise<void>;
/**
* Manually dequeue and mark the next job as completed without processing.
* This is primarily used for testing or manual job management.
*
* @returns Promise<BaseJob | null> resolving to the dequeued job or null if no jobs available
*
* @example
* ```typescript
* // Manually dequeue next job
* const job = await queue.dequeue()
* if (job) {
* console.log(`Dequeued job: ${job.name}`)
* }
* ```
*/
dequeue(): Promise<BaseJob | null>;
/**
* Listen to queue events.
*
* @param event Event name to listen for
* @param listener Event handler function
*
* @example
* ```typescript
* queue.on("job:completed", (job) => {
* console.log(`Job ${job.name} completed successfully`)
* })
*
* queue.on("job:failed", (job) => {
* console.error(`Job ${job.name} failed: ${job.error}`)
* })
* ```
*/
on<TEventName extends keyof QueueEvents>(event: TEventName, listener: EventListener<QueueEvents[TEventName]>): void;
/**
* Internal method to emit queue events to registered listeners.
*
* @param event Event name to emit
* @param data Event data to pass to listeners
* @private
*
* @example
* ```typescript
* this.emit("job:completed", completedJobData)
* this.emit("queue:error", errorData)
* ```
*/
private emit;
/**
* Internal polling method that continuously checks for and processes jobs.
* Handles concurrency limits and processing intervals.
*
* @returns Promise that resolves when polling is stopped
* @private
*/
private poll;
/**
* Internal method to dequeue and process a single job.
*
* @returns Promise resolving to boolean indicating if job was processed
* @private
*/
private dequeueAndProcess;
/**
* Internal method to process a job using its registered handler.
* Handles job timeouts, completion, cleanup and recurring job scheduling.
*
* @param job The job to process
* @returns Promise that resolves when job processing is complete
* @private
*/
private processJob;
/**
* Internal method to handle job errors.
* Determines whether to retry or fail the job based on attempt count.
*
* @param job The failed job
* @param error The error that occurred
* @returns Promise that resolves when error handling is complete
* @private
*/
private handleJobError;
/**
* Internal method to retry a failed job.
* Increments attempt count and schedules next attempt with backoff delay.
*
* @param job The job to retry
* @param _error The error from the failed attempt
* @returns Promise that resolves when job is scheduled for retry
* @private
*/
private retryJob;
/**
* Internal method to mark a job as permanently failed.
* Updates job status and triggers cleanup of failed jobs.
*
* @param job The job to fail
* @param error The error that caused the failure
* @returns Promise that resolves when job is marked as failed
* @private
*/
private failJob;
/**
* Internal method to clean up completed jobs based on queue configuration.
* Can remove jobs immediately, keep all jobs, or maintain a fixed number of completed jobs.
*
* @returns Promise that resolves when cleanup is complete
* @private
*/
private cleanupCompletedJob;
/**
* Internal method to clean up failed jobs based on queue configuration.
* Can remove jobs immediately, keep all jobs, or maintain a fixed number of failed jobs.
*
* @returns Promise that resolves when cleanup is complete
* @private
*/
private cleanupFailedJob;
/**
* Internal method to handle recurring job scheduling.
* Creates the next occurrence of recurring jobs based on cron or repeat interval.
*
* @param job The completed job that may need to be rescheduled
* @param originalTimezone Optional timezone for cron scheduling
* @returns Promise that resolves when next job is scheduled
* @private
*/
private handleRecurringJob;
}
export {};