@buenojs/bueno 0.8.4 → 0.8.6

package/src/jobs/queue.ts

@@ -0,0 +1,281 @@
+/**
+ * Job Queue Factory and API
+ *
+ * Main public interface for enqueueing and managing background jobs.
+ * Supports both Redis and in-memory drivers.
+ */
+
+import { MemoryJobQueueDriver } from "./drivers/memory";
+import { RedisJobQueueDriver } from "./drivers/redis";
+import type {
+	HandlerRegistryEntry,
+	Job,
+	JobEvent,
+	JobEventType,
+	JobHandler,
+	JobQueueConfig,
+	JobQueueDriver,
+	QueueMetrics,
+	QueueOptions,
+} from "./types";
+
+// ============= Job Queue Class =============
+
+export class JobQueue {
+	private driver: JobQueueDriver;
+	private handlers: Map<string, JobHandler<unknown>> = new Map();
+	private handlerRegistry: HandlerRegistryEntry[] = [];
+	private eventListeners: Map<JobEventType, Set<(event: JobEvent) => void>> =
+		new Map();
+	private isRunning = false;
+
+	constructor(config: JobQueueConfig = {}) {
+		// Instantiate appropriate driver
+		const driver = config.driver ?? "memory";
+
+		if (driver === "redis") {
+			if (!config.url) {
+				throw new Error("Redis URL is required for Redis driver");
+			}
+			this.driver = new RedisJobQueueDriver(config);
+		} else {
+			this.driver = new MemoryJobQueueDriver(config);
+		}
+	}
+
+	/**
+	 * Initialize the queue (connect to backend)
+	 */
+	async init(): Promise<void> {
+		await this.driver.connect();
+	}
+
+	/**
+	 * Shutdown the queue gracefully
+	 */
+	async shutdown(): Promise<void> {
+		this.isRunning = false;
+		await this.driver.disconnect();
+	}
+
+	/**
+	 * Enqueue a job
+	 * @param name - Job name/type (e.g., "email.welcome")
+	 * @param data - Job payload
+	 * @param options - Queue options (delay, priority, timeout)
+	 * @returns Job ID
+	 */
+	async enqueue<T = unknown>(
+		name: string,
+		data: T,
+		options?: QueueOptions,
+	): Promise<string> {
+		const jobId = await this.driver.enqueue(name, data, options);
+		this._emitEvent("enqueued", { id: jobId, name } as unknown as Job);
+		return jobId;
+	}
+
+	/**
+	 * Register a handler for a job type
+	 * Supports wildcards: "email.*" matches "email.welcome", "email.reset", etc.
+	 */
+	on(pattern: string, handler: JobHandler<unknown>): void {
+		this.handlers.set(pattern, handler);
+
+		// Calculate specificity for wildcard matching (longer = more specific)
+		const specificity = pattern.split(".").length;
+		const entry: HandlerRegistryEntry = { pattern, handler, specificity };
+
+		// Insert in order of specificity (highest first)
+		const index = this.handlerRegistry.findIndex(
+			(e) => e.specificity < specificity,
+		);
+		if (index >= 0) {
+			this.handlerRegistry.splice(index, 0, entry);
+		} else {
+			this.handlerRegistry.push(entry);
+		}
+	}
+
+	/**
+	 * Remove a handler
+	 */
+	off(pattern: string): void {
+		this.handlers.delete(pattern);
+		const index = this.handlerRegistry.findIndex((e) => e.pattern === pattern);
+		if (index >= 0) {
+			this.handlerRegistry.splice(index, 1);
+		}
+	}
+
+	/**
+	 * Find the best matching handler for a job
+	 */
+	private findHandler(jobName: string): JobHandler<unknown> | null {
+		for (const entry of this.handlerRegistry) {
+			if (this._patternMatches(entry.pattern, jobName)) {
+				return entry.handler;
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Check if a pattern matches a job name (supports wildcards)
+	 */
+	private _patternMatches(pattern: string, jobName: string): boolean {
+		if (pattern === jobName) return true;
+
+		// Handle wildcards: "email.*" matches "email.welcome"
+		if (pattern.endsWith(".*")) {
+			const prefix = pattern.slice(0, -2); // Remove ".*"
+			return jobName.startsWith(prefix + ".");
+		}
+
+		return false;
+	}
+
+	/**
+	 * Listen for queue events
+	 */
+	onEvent(event: JobEventType, listener: (event: JobEvent) => void): void {
+		if (!this.eventListeners.has(event)) {
+			this.eventListeners.set(event, new Set());
+		}
+		this.eventListeners.get(event)!.add(listener);
+	}
+
+	/**
+	 * Stop listening for queue events
+	 */
+	offEvent(event: JobEventType, listener: (event: JobEvent) => void): void {
+		this.eventListeners.get(event)?.delete(listener);
+	}
+
+	/**
+	 * Emit a queue event
+	 */
+	private _emitEvent(eventType: JobEventType, job: Job): void {
+		const listeners = this.eventListeners.get(eventType);
+		if (!listeners) return;
+
+		const event: JobEvent = {
+			type: eventType,
+			job,
+			timestamp: new Date(),
+		};
+
+		for (const listener of listeners) {
+			try {
+				listener(event);
+			} catch (error) {
+				console.error(`Error in ${eventType} listener:`, error);
+			}
+		}
+	}
+
+	/**
+	 * Start the polling loop (for tests/manual control)
+	 * Note: In production, use a separate worker process
+	 */
+	async start(
+		options: { pollInterval?: number; concurrency?: number } = {},
+	): Promise<void> {
+		this.isRunning = true;
+		const pollInterval = options.pollInterval ?? 1000;
+		const concurrency = options.concurrency ?? 10;
+
+		// This is a basic polling loop for simple use cases
+		// For production, use a dedicated worker process with JobWorker class
+		while (this.isRunning) {
+			try {
+				const jobs = await this.driver.claim(concurrency, 30000);
+
+				for (const job of jobs) {
+					if (!this.isRunning) break;
+
+					try {
+						const handler = this.findHandler(job.name);
+						if (!handler) {
+							console.warn(`No handler found for job type: ${job.name}`);
+							await this.driver.complete(job.id);
+							continue;
+						}
+
+						this._emitEvent("started", job);
+
+						await handler(job);
+
+						this._emitEvent("completed", job);
+						await this.driver.complete(job.id);
+					} catch (error) {
+						const errorMsg =
+							error instanceof Error ? error.message : String(error);
+						const stackTrace = error instanceof Error ? error.stack : undefined;
+
+						if (job.attempts < job.maxRetries) {
+							const backoffMs = Math.pow(2, job.attempts) * 1000; // Exponential backoff
+							this._emitEvent("retried", job);
+							await this.driver.scheduleRetry(job.id, backoffMs, errorMsg);
+						} else {
+							this._emitEvent("failed", job);
+							await this.driver.fail(job.id, errorMsg, stackTrace);
+						}
+					}
+				}
+
+				// Sleep before next poll
+				await new Promise((resolve) => setTimeout(resolve, pollInterval));
+			} catch (error) {
+				console.error("Error in job queue polling loop:", error);
+				await new Promise((resolve) => setTimeout(resolve, pollInterval));
+			}
+		}
+	}
+
+	/**
+	 * Stop the polling loop
+	 */
+	async stop(): Promise<void> {
+		this.isRunning = false;
+		// Wait a bit for current jobs to finish
+		await new Promise((resolve) => setTimeout(resolve, 1000));
+	}
+
+	/**
+	 * Get a job by ID
+	 */
+	async getJob(jobId: string): Promise<Job | null> {
+		return this.driver.getJob(jobId);
+	}
+
+	/**
+	 * Get queue metrics
+	 */
+	async getMetrics(): Promise<QueueMetrics> {
+		return this.driver.getMetrics();
+	}
+
+	/**
+	 * Clear all jobs (use with caution!)
+	 */
+	async clear(): Promise<void> {
+		return this.driver.clear();
+	}
+
+	/**
+	 * Check if queue is connected
+	 */
+	async isConnected(): Promise<boolean> {
+		return this.driver.isConnected();
+	}
+}
+
+// ============= Factory Function =============
+
+/**
+ * Create a new job queue instance
+ */
+export function createJobQueue(config?: JobQueueConfig): JobQueue {
+	return new JobQueue(config);
+}

package/src/jobs/types.ts

@@ -0,0 +1,295 @@
+/**
+ * Background Jobs / Task Queue
+ *
+ * Type definitions for the job queue system.
+ * Supports Redis (production) and in-memory (development) drivers.
+ */
+
+// ============= Job Status =============
+
+export type JobStatus =
+	| "pending"
+	| "processing"
+	| "completed"
+	| "failed"
+	| "delayed";
+
+// ============= Job Data Structure =============
+
+/**
+ * Represents a background job
+ */
+export interface Job<T = unknown> {
+	/** Unique job identifier */
+	id: string;
+
+	/** Job name/type (e.g., "email.welcome", "image.resize") */
+	name: string;
+
+	/** Job payload data */
+	data: T;
+
+	/** Current status of the job */
+	status: JobStatus;
+
+	/** Number of times this job has been attempted */
+	attempts: number;
+
+	/** Maximum number of retry attempts */
+	maxRetries: number;
+
+	/** Error message if job failed */
+	error?: string;
+
+	/** Stack trace if job failed */
+	stackTrace?: string;
+
+	/** When the job was created (ISO 8601) */
+	createdAt: string;
+
+	/** When the job was last updated (ISO 8601) */
+	updatedAt: string;
+
+	/** When the job should start (ISO 8601, for delayed jobs) */
+	scheduledFor?: string;
+
+	/** When job processing started (ISO 8601) */
+	startedAt?: string;
+
+	/** When job processing completed (ISO 8601) */
+	completedAt?: string;
+
+	/** How long the job took to complete in milliseconds */
+	duration?: number;
+
+	/** Job priority (higher = process sooner) */
+	priority?: number;
+
+	/** Custom metadata attached to the job */
+	metadata?: Record<string, unknown>;
+
+	/** Worker that claimed this job */
+	workerId?: string;
+
+	/** When the job claim expires (for dead letter handling) */
+	claimExpiresAt?: string;
+}
+
+// ============= Queue Configuration =============
+
+export interface JobQueueConfig {
+	/** Driver type: 'redis' for production, 'memory' for development */
+	driver?: "redis" | "memory";
+
+	/** Redis connection URL (required if driver is 'redis') */
+	url?: string;
+
+	/** Key prefix for all jobs (default: 'jobs:') */
+	keyPrefix?: string;
+
+	/** Maximum number of jobs to process concurrently (default: 10) */
+	concurrency?: number;
+
+	/** Maximum number of retry attempts (default: 3) */
+	maxRetries?: number;
+
+	/** Base delay in seconds for exponential backoff (default: 1) */
+	retryDelay?: number;
+
+	/** Number of jobs to claim in a single poll (default: 10) */
+	batchSize?: number;
+
+	/** Polling interval in milliseconds (default: 1000) */
+	pollInterval?: number;
+
+	/** Job timeout in milliseconds (default: 300000 / 5 minutes) */
+	jobTimeout?: number;
+
+	/** Enable metrics collection (default: true) */
+	enableMetrics?: boolean;
+}
+
+// ============= Enqueue Options =============
+
+export interface QueueOptions {
+	/** Schedule job for later execution (ISO 8601 or Date) */
+	delay?: number | Date;
+
+	/** Job priority (default: 0) */
+	priority?: number;
+
+	/** Custom metadata */
+	metadata?: Record<string, unknown>;
+
+	/** Override default job timeout in milliseconds */
+	timeout?: number;
+
+	/** Maximum retries for this specific job */
+	maxRetries?: number;
+}
+
+// ============= Handler Type =============
+
+/**
+ * Async handler function for processing jobs
+ */
+export type JobHandler<T = unknown> = (job: Job<T>) => Promise<void>;
+
+// ============= Queue Metrics =============
+
+/**
+ * Metrics for job queue observability
+ */
+export interface QueueMetrics {
+	/** Total jobs enqueued */
+	enqueued: number;
+
+	/** Jobs successfully completed */
+	processed: number;
+
+	/** Jobs that failed (exceeded max retries) */
+	failed: number;
+
+	/** Jobs currently in pending state */
+	pending: number;
+
+	/** Jobs currently being processed */
+	processing: number;
+
+	/** Average job processing time in milliseconds */
+	avgLatency: number;
+
+	/** Total processing time in milliseconds */
+	totalLatency: number;
+
+	/** Number of job retries that occurred */
+	retried: number;
+
+	/** Success rate (0.0 to 1.0) */
+	successRate: number;
+
+	/** Average number of attempts per job */
+	avgAttempts: number;
+}
+
+// ============= Events =============
+
+export type JobEventType =
+	| "enqueued"
+	| "started"
+	| "completed"
+	| "failed"
+	| "retried";
+
+export interface JobEvent<T = unknown> {
+	type: JobEventType;
+	job: Job<T>;
+	timestamp: Date;
+	metadata?: Record<string, unknown>;
+}
+
+// ============= Lock Handle for Job Claims =============
+
+export interface JobClaimHandle {
+	/** Whether the claim was successfully acquired */
+	acquired: boolean;
+
+	/** Release the claim (job goes back to pending) */
+	release: () => Promise<boolean>;
+
+	/** Extend the claim TTL for long-running jobs */
+	extend: (ttl?: number) => Promise<boolean>;
+
+	/** Check if claim is still valid */
+	isValid: () => Promise<boolean>;
+
+	/** Get remaining TTL in milliseconds */
+	getRemainingTTL: () => Promise<number>;
+
+	/** The claim key */
+	key: string;
+
+	/** The claim value (unique identifier) */
+	value: string;
+}
+
+// ============= Driver Interface =============
+
+/**
+ * Interface that both Redis and Memory drivers must implement
+ */
+export interface JobQueueDriver {
+	/**
+	 * Initialize the driver (e.g., connect to Redis)
+	 */
+	connect(): Promise<void>;
+
+	/**
+	 * Disconnect from the driver
+	 */
+	disconnect(): Promise<void>;
+
+	/**
+	 * Check if connected
+	 */
+	isConnected(): Promise<boolean>;
+
+	/**
+	 * Enqueue a new job
+	 */
+	enqueue<T = unknown>(
+		name: string,
+		data: T,
+		options?: QueueOptions,
+	): Promise<string>;
+
+	/**
+	 * Claim a batch of pending jobs for processing
+	 */
+	claim(count: number, timeout: number): Promise<Job[]>;
+
+	/**
+	 * Mark a job as completed
+	 */
+	complete(jobId: string): Promise<void>;
+
+	/**
+	 * Mark a job as failed
+	 */
+	fail(jobId: string, error: string, stackTrace?: string): Promise<void>;
+
+	/**
+	 * Schedule a job for retry
+	 */
+	scheduleRetry(jobId: string, delayMs: number, error: string): Promise<void>;
+
+	/**
+	 * Get a job by ID
+	 */
+	getJob(jobId: string): Promise<Job | null>;
+
+	/**
+	 * Get queue metrics
+	 */
+	getMetrics(): Promise<QueueMetrics>;
+
+	/**
+	 * Clear all jobs from the queue (use with caution!)
+	 */
+	clear(): Promise<void>;
+}
+
+// ============= Handler Registry Entry =============
+
+export interface HandlerRegistryEntry {
+	pattern: string;
+	handler: JobHandler<unknown>;
+	specificity: number; // For wildcard matching priority
+}
+
+// ============= Configuration Validation =============
+
+export interface JobConfigValidationResult {
+	valid: boolean;
+	errors: string[];
+}