@buenojs/bueno 0.8.4 → 0.8.6

package/src/jobs/worker.ts

@@ -0,0 +1,380 @@
+/**
+ * Job Worker
+ *
+ * Production-grade worker for processing background jobs.
+ * Designed to run in a separate process/worker.
+ * Supports graceful shutdown and exponential backoff polling.
+ */
+
+import { MemoryJobQueueDriver } from "./drivers/memory";
+import { RedisJobQueueDriver } from "./drivers/redis";
+import type {
+	HandlerRegistryEntry,
+	Job,
+	JobEvent,
+	JobEventType,
+	JobHandler,
+	JobQueueConfig,
+	JobQueueDriver,
+} from "./types";
+
+// ============= Job Worker Class =============
+
+export class JobWorker {
+	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;
+	private pollInterval: number;
+	private concurrency: number;
+	private jobTimeout: number;
+	private maxBackoffDelay = 30000; // 30 seconds max backoff
+	private currentBackoff = 0;
+	private inFlightJobs = new Set<string>();
+	private shutdownTimeout = 10000; // 10 seconds to drain
+
+	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);
+		}
+
+		this.pollInterval = config.pollInterval ?? 1000;
+		this.concurrency = config.concurrency ?? 10;
+		this.jobTimeout = config.jobTimeout ?? 300000; // 5 minutes default
+	}
+
+	/**
+	 * Initialize the worker (connect to backend)
+	 */
+	async init(): Promise<void> {
+		await this.driver.connect();
+	}
+
+	/**
+	 * Register a handler for a job type
+	 * Supports wildcards: "email.*" matches "email.welcome", "email.reset", etc.
+	 */
+	handle(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
+	 */
+	unhandle(pattern: string): void {
+		this.handlers.delete(pattern);
+		const index = this.handlerRegistry.findIndex((e) => e.pattern === pattern);
+		if (index >= 0) {
+			this.handlerRegistry.splice(index, 1);
+		}
+	}
+
+	/**
+	 * Listen for worker events
+	 */
+	on(eventType: JobEventType, listener: (event: JobEvent) => void): void {
+		if (!this.eventListeners.has(eventType)) {
+			this.eventListeners.set(eventType, new Set());
+		}
+		this.eventListeners.get(eventType)!.add(listener);
+	}
+
+	/**
+	 * Stop listening for events
+	 */
+	off(eventType: JobEventType, listener: (event: JobEvent) => void): void {
+		this.eventListeners.get(eventType)?.delete(listener);
+	}
+
+	/**
+	 * Emit a worker 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);
+			}
+		}
+	}
+
+	/**
+	 * 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;
+	}
+
+	/**
+	 * Start the worker (blocks until stopped)
+	 */
+	async start(): Promise<void> {
+		this.isRunning = true;
+
+		console.log("[JobWorker] Starting worker process");
+
+		// Handle signals for graceful shutdown
+		const handleSignal = async () => {
+			await this.stop();
+		};
+
+		process.on("SIGTERM", handleSignal);
+		process.on("SIGINT", handleSignal);
+
+		try {
+			await this._pollLoop();
+		} finally {
+			process.removeListener("SIGTERM", handleSignal);
+			process.removeListener("SIGINT", handleSignal);
+		}
+	}
+
+	/**
+	 * Main polling loop
+	 */
+	private async _pollLoop(): Promise<void> {
+		while (this.isRunning) {
+			try {
+				const availableSlots = this.concurrency - this.inFlightJobs.size;
+
+				if (availableSlots > 0) {
+					const jobs = await this.driver.claim(availableSlots, this.jobTimeout);
+
+					if (jobs.length > 0) {
+						// Reset backoff on successful claim
+						this.currentBackoff = 0;
+
+						// Process jobs concurrently
+						for (const job of jobs) {
+							this._processJob(job).catch((error) => {
+								console.error(
+									`[JobWorker] Unhandled error processing job ${job.id}:`,
+									error,
+								);
+							});
+						}
+					} else {
+						// No jobs, increase backoff
+						this.currentBackoff = Math.min(
+							(this.currentBackoff || this.pollInterval) * 1.5,
+							this.maxBackoffDelay,
+						);
+					}
+				}
+
+				// Sleep before next poll
+				const delay = this.currentBackoff || this.pollInterval;
+				await new Promise((resolve) => setTimeout(resolve, delay));
+			} catch (error) {
+				console.error("[JobWorker] Error in polling loop:", error);
+
+				// Backoff on error
+				this.currentBackoff = Math.min(
+					(this.currentBackoff || this.pollInterval) * 1.5,
+					this.maxBackoffDelay,
+				);
+
+				await new Promise((resolve) =>
+					setTimeout(resolve, this.currentBackoff),
+				);
+			}
+		}
+	}
+
+	/**
+	 * Process a single job
+	 */
+	private async _processJob(job: Job): Promise<void> {
+		this.inFlightJobs.add(job.id);
+
+		try {
+			const handler = this.findHandler(job.name);
+
+			if (!handler) {
+				console.warn(`[JobWorker] No handler found for job type: ${job.name}`);
+				await this.driver.complete(job.id);
+				return;
+			}
+
+			this._emitEvent("started", job);
+
+			// Execute handler with timeout
+			const timeoutPromise = new Promise((_, reject) =>
+				setTimeout(
+					() => reject(new Error(`Job timeout after ${this.jobTimeout}ms`)),
+					this.jobTimeout,
+				),
+			);
+
+			const handlerPromise = handler(job);
+
+			await Promise.race([handlerPromise, timeoutPromise]);
+
+			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;
+
+			// Determine if we should retry
+			if (job.attempts < job.maxRetries) {
+				// Exponential backoff: 1s, 2s, 4s, 8s, etc. (capped at 1 hour)
+				const delaySeconds = Math.min(Math.pow(2, job.attempts), 3600);
+				const delayMs = delaySeconds * 1000;
+
+				this._emitEvent("retried", job);
+				await this.driver.scheduleRetry(job.id, delayMs, errorMsg);
+
+				console.warn(
+					`[JobWorker] Job ${job.id} failed (attempt ${job.attempts}/${job.maxRetries}): ${errorMsg}. Retrying in ${delaySeconds}s`,
+				);
+			} else {
+				this._emitEvent("failed", job);
+				await this.driver.fail(job.id, errorMsg, stackTrace);
+
+				console.error(
+					`[JobWorker] Job ${job.id} failed permanently: ${errorMsg}`,
+				);
+			}
+		} finally {
+			this.inFlightJobs.delete(job.id);
+		}
+	}
+
+	/**
+	 * Stop the worker gracefully
+	 * Waits for in-flight jobs to complete before shutdown
+	 */
+	async stop(): Promise<void> {
+		if (!this.isRunning) return;
+
+		console.log("[JobWorker] Shutting down gracefully...");
+		this.isRunning = false;
+
+		// Wait for in-flight jobs to complete
+		const startTime = Date.now();
+		while (
+			this.inFlightJobs.size > 0 &&
+			Date.now() - startTime < this.shutdownTimeout
+		) {
+			await new Promise((resolve) => setTimeout(resolve, 100));
+		}
+
+		if (this.inFlightJobs.size > 0) {
+			console.warn(
+				`[JobWorker] Force shutdown with ${this.inFlightJobs.size} jobs still in flight`,
+			);
+		} else {
+			console.log("[JobWorker] All jobs completed, shutting down");
+		}
+
+		await this.driver.disconnect();
+	}
+
+	/**
+	 * Get the number of jobs currently being processed
+	 */
+	getInFlightCount(): number {
+		return this.inFlightJobs.size;
+	}
+
+	/**
+	 * Get queue metrics
+	 */
+	async getMetrics() {
+		return this.driver.getMetrics();
+	}
+
+	/**
+	 * Check if worker is running
+	 */
+	isActive(): boolean {
+		return this.isRunning;
+	}
+}
+
+// ============= Worker CLI Entry Point =============
+
+/**
+ * Create and start a worker from config
+ * Useful for CLI commands like: bueno queue:worker
+ */
+export async function startWorker(config?: JobQueueConfig): Promise<void> {
+	const worker = new JobWorker(config);
+
+	// Log metrics periodically
+	const metricsInterval = setInterval(async () => {
+		if (worker.isActive()) {
+			const metrics = await worker.getMetrics();
+			console.log("[JobWorker] Metrics:", {
+				pending: metrics.pending,
+				processing: metrics.processing,
+				processed: metrics.processed,
+				failed: metrics.failed,
+				avgLatency: `${Math.round(metrics.avgLatency)}ms`,
+			});
+		}
+	}, 30000);
+
+	await worker.init();
+
+	process.on("exit", () => {
+		clearInterval(metricsInterval);
+	});
+
+	await worker.start();
+}

package/src/logger/index.ts

@@ -372,9 +372,7 @@ export class PerformanceLogger {
 	/**
 	 * Get metric statistics
 	 */
-	stats(
-		name: string,
-	): {
+	stats(name: string): {
 		count: number;
 		min: number;
 		max: number;

package/src/logger/transports/index.ts

@@ -12,7 +12,10 @@ import type { LogEntry, LogLevel, LoggerConfig } from "../index";
 /**
  * Error callback for transport errors
  */
-export type TransportErrorCallback = (error: Error, transport: LogTransport) => void;
+export type TransportErrorCallback = (
+	error: Error,
+	transport: LogTransport,
+) => void;
 
 /**
  * Base interface for log transports
@@ -192,7 +195,7 @@ export class HTTPWebhookTransport implements LogTransport {
 					await this.sleep(delay);
 					delay = Math.min(
 						delay * this.retryOptions.backoffMultiplier,
-						this.retryOptions.maxDelay
+						this.retryOptions.maxDelay,
 					);
 				}
 			}
@@ -259,7 +262,9 @@ export class HTTPWebhookTransport implements LogTransport {
 			try {
 				await this.flush();
 			} catch (error) {
-				this.handleError(error instanceof Error ? error : new Error(String(error)));
+				this.handleError(
+					error instanceof Error ? error : new Error(String(error)),
+				);
 			}
 		}
 	}
@@ -337,7 +342,8 @@ export class DatadogTransport implements LogTransport {
 		this.env = options.env ?? process.env.NODE_ENV ?? "development";
 		this.hostname = options.hostname ?? this.getDefaultHostname();
 		this.tags = options.tags ?? [];
-		this.endpoint = options.endpoint ?? "https://http-intake.logs.datadoghq.com/v1/input";
+		this.endpoint =
+			options.endpoint ?? "https://http-intake.logs.datadoghq.com/v1/input";
 		this.batchSize = options.batchSize ?? 100;
 		this.flushInterval = options.flushInterval ?? 5000;
 		this.timeout = options.timeout ?? 30000;
@@ -395,7 +401,7 @@ export class DatadogTransport implements LogTransport {
 	 */
 	private toDatadogFormat(entry: LogEntry): DatadogLogEntry {
 		const allTags = [...this.tags];
-		
+
 		// Add environment tag
 		if (this.env) {
 			allTags.push(`env:${this.env}`);
@@ -404,7 +410,11 @@ export class DatadogTransport implements LogTransport {
 		// Add context as tags
 		if (entry.context) {
 			for (const [key, value] of Object.entries(entry.context)) {
-				if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+				if (
+					typeof value === "string" ||
+					typeof value === "number" ||
+					typeof value === "boolean"
+				) {
 					allTags.push(`${key}:${value}`);
 				}
 			}
@@ -437,7 +447,16 @@ export class DatadogTransport implements LogTransport {
 
 		// Add any additional fields from the entry
 		for (const [key, value] of Object.entries(entry)) {
-			if (!["level", "message", "timestamp", "context", "error", "duration"].includes(key)) {
+			if (
+				![
+					"level",
+					"message",
+					"timestamp",
+					"context",
+					"error",
+					"duration",
+				].includes(key)
+			) {
 				datadogEntry[key] = value;
 			}
 		}
@@ -510,7 +529,7 @@ export class DatadogTransport implements LogTransport {
 					await this.sleep(delay);
 					delay = Math.min(
 						delay * this.retryOptions.backoffMultiplier,
-						this.retryOptions.maxDelay
+						this.retryOptions.maxDelay,
 					);
 				}
 			}
@@ -540,7 +559,9 @@ export class DatadogTransport implements LogTransport {
 			});
 
 			if (!response.ok) {
-				throw new Error(`Datadog API error: HTTP ${response.status}: ${response.statusText}`);
+				throw new Error(
+					`Datadog API error: HTTP ${response.status}: ${response.statusText}`,
+				);
 			}
 		} finally {
 			clearTimeout(timeoutId);
@@ -579,7 +600,9 @@ export class DatadogTransport implements LogTransport {
 			try {
 				await this.flush();
 			} catch (error) {
-				this.handleError(error instanceof Error ? error : new Error(String(error)));
+				this.handleError(
+					error instanceof Error ? error : new Error(String(error)),
+				);
 			}
 		}
 	}
@@ -680,7 +703,10 @@ export class ConsoleTransport implements LogTransport {
 			this.output(formatted, entry.level);
 		} catch (error) {
 			if (this.onError) {
-				this.onError(error instanceof Error ? error : new Error(String(error)), this);
+				this.onError(
+					error instanceof Error ? error : new Error(String(error)),
+					this,
+				);
 			}
 		}
 	}
@@ -766,7 +792,10 @@ export class TransportManager {
 				await transport.send(entry);
 			} catch (error) {
 				if (this.onError) {
-					this.onError(error instanceof Error ? error : new Error(String(error)), transport);
+					this.onError(
+						error instanceof Error ? error : new Error(String(error)),
+						transport,
+					);
 				}
 			}
 		});
@@ -783,7 +812,10 @@ export class TransportManager {
 				await transport.sendBatch(entries);
 			} catch (error) {
 				if (this.onError) {
-					this.onError(error instanceof Error ? error : new Error(String(error)), transport);
+					this.onError(
+						error instanceof Error ? error : new Error(String(error)),
+						transport,
+					);
 				}
 			}
 		});
@@ -801,7 +833,10 @@ export class TransportManager {
 					await transport.flush();
 				} catch (error) {
 					if (this.onError) {
-						this.onError(error instanceof Error ? error : new Error(String(error)), transport);
+						this.onError(
+							error instanceof Error ? error : new Error(String(error)),
+							transport,
+						);
 					}
 				}
 			}
@@ -820,7 +855,10 @@ export class TransportManager {
 					await transport.close();
 				} catch (error) {
 					if (this.onError) {
-						this.onError(error instanceof Error ? error : new Error(String(error)), transport);
+						this.onError(
+							error instanceof Error ? error : new Error(String(error)),
+							transport,
+						);
 					}
 				}
 			}
@@ -853,10 +891,12 @@ export class LoggerWithTransports extends Logger {
 
 	constructor(config: LoggerWithTransportsConfig = {}) {
 		const { transports, onTransportError, ...loggerConfig } = config;
-		
+
 		// Create transport manager
-		const transportManager = new TransportManager({ onError: onTransportError });
-		
+		const transportManager = new TransportManager({
+			onError: onTransportError,
+		});
+
 		// Add transports
 		if (transports) {
 			for (const transport of transports) {
@@ -931,7 +971,7 @@ export class LoggerWithTransports extends Logger {
  * Create a logger with transports
  */
 export function createLoggerWithTransports(
-	config: LoggerWithTransportsConfig = {}
+	config: LoggerWithTransportsConfig = {},
 ): LoggerWithTransports {
 	return new LoggerWithTransports(config);
 }
@@ -941,10 +981,10 @@ export function createLoggerWithTransports(
  */
 export function createTransportOutput(
 	transports: LogTransport[],
-	options?: { onError?: TransportErrorCallback }
+	options?: { onError?: TransportErrorCallback },
 ): (entry: LogEntry) => void {
 	const manager = new TransportManager({ onError: options?.onError });
-	
+
 	for (const transport of transports) {
 		manager.addTransport(transport);
 	}
@@ -966,4 +1006,4 @@ export default {
 	LoggerWithTransports,
 	createLoggerWithTransports,
 	createTransportOutput,
-};
+};

package/src/metrics/index.ts

@@ -167,9 +167,7 @@ export async function measureEventLoopLag(): Promise<number> {
 /**
  * Measure event loop lag multiple times and return average
  */
-export async function measureEventLoopLagAverage(
-	samples: number = 5,
-): Promise<number> {
+export async function measureEventLoopLagAverage(samples = 5): Promise<number> {
 	const measurements: number[] = [];
 
 	for (let i = 0; i < samples; i++) {
@@ -243,7 +241,7 @@ export class MetricsCollector {
 	 * Start collecting metrics at regular intervals
 	 * @param intervalMs Interval in milliseconds (default: 5000)
 	 */
-	startPeriodicCollection(intervalMs: number = 5000): void {
+	startPeriodicCollection(intervalMs = 5000): void {
 		if (this.periodicTimer !== null) {
 			throw new Error("Periodic collection is already running");
 		}
@@ -310,7 +308,7 @@ export class MetricsCollector {
 		let sumCpuUser = 0;
 		let sumCpuSystem = 0;
 		let sumEventLoopLag = 0;
-		let minHeapUsed = Infinity;
+		let minHeapUsed = Number.POSITIVE_INFINITY;
 		let maxHeapUsed = 0;
 
 		for (const m of this.history) {
@@ -333,7 +331,8 @@ export class MetricsCollector {
 			avgCpuUser: Math.round(sumCpuUser / count),
 			avgCpuSystem: Math.round(sumCpuSystem / count),
 			avgEventLoopLag: Math.round((sumEventLoopLag / count) * 100) / 100,
-			minMemoryHeapUsed: minHeapUsed === Infinity ? 0 : minHeapUsed,
+			minMemoryHeapUsed:
+				minHeapUsed === Number.POSITIVE_INFINITY ? 0 : minHeapUsed,
 			maxMemoryHeapUsed: maxHeapUsed,
 			sampleCount: count,
 			timeRange: {
@@ -377,7 +376,9 @@ export function toPrometheusFormat(metrics: RuntimeMetrics): string {
 		`process_memory_heap_used_bytes ${metrics.memoryHeapUsed} ${timestamp}`,
 	);
 
-	lines.push("# HELP process_memory_heap_total_bytes Total heap memory in bytes");
+	lines.push(
+		"# HELP process_memory_heap_total_bytes Total heap memory in bytes",
+	);
 	lines.push("# TYPE process_memory_heap_total_bytes gauge");
 	lines.push(
 		`process_memory_heap_total_bytes ${metrics.memoryHeapTotal} ${timestamp}`,
@@ -409,7 +410,9 @@ export function toPrometheusFormat(metrics: RuntimeMetrics): string {
 	// Runtime metrics
 	lines.push("# HELP process_uptime_seconds Process uptime in seconds");
 	lines.push("# TYPE process_uptime_seconds gauge");
-	lines.push(`process_uptime_seconds ${metrics.uptime.toFixed(2)} ${timestamp}`);
+	lines.push(
+		`process_uptime_seconds ${metrics.uptime.toFixed(2)} ${timestamp}`,
+	);
 
 	lines.push("# HELP nodejs_eventloop_lag_ms Event loop lag in milliseconds");
 	lines.push("# TYPE nodejs_eventloop_lag_ms gauge");
@@ -423,25 +426,29 @@ export function toPrometheusFormat(metrics: RuntimeMetrics): string {
 /**
  * Export averaged metrics in Prometheus format
  */
-export function averagedMetricsToPrometheus(
-	averaged: AveragedMetrics,
-): string {
+export function averagedMetricsToPrometheus(averaged: AveragedMetrics): string {
 	const timestamp = Date.now();
 	const lines: string[] = [];
 
-	lines.push("# HELP process_memory_heap_used_avg_bytes Average heap memory used");
+	lines.push(
+		"# HELP process_memory_heap_used_avg_bytes Average heap memory used",
+	);
 	lines.push("# TYPE process_memory_heap_used_avg_bytes gauge");
 	lines.push(
 		`process_memory_heap_used_avg_bytes ${averaged.avgMemoryHeapUsed} ${timestamp}`,
 	);
 
-	lines.push("# HELP process_memory_heap_used_min_bytes Minimum heap memory used");
+	lines.push(
+		"# HELP process_memory_heap_used_min_bytes Minimum heap memory used",
+	);
 	lines.push("# TYPE process_memory_heap_used_min_bytes gauge");
 	lines.push(
 		`process_memory_heap_used_min_bytes ${averaged.minMemoryHeapUsed} ${timestamp}`,
 	);
 
-	lines.push("# HELP process_memory_heap_used_max_bytes Maximum heap memory used");
+	lines.push(
+		"# HELP process_memory_heap_used_max_bytes Maximum heap memory used",
+	);
 	lines.push("# TYPE process_memory_heap_used_max_bytes gauge");
 	lines.push(
 		`process_memory_heap_used_max_bytes ${averaged.maxMemoryHeapUsed} ${timestamp}`,
@@ -455,7 +462,9 @@ export function averagedMetricsToPrometheus(
 
 	lines.push("# HELP process_metrics_sample_count Number of samples collected");
 	lines.push("# TYPE process_metrics_sample_count gauge");
-	lines.push(`process_metrics_sample_count ${averaged.sampleCount} ${timestamp}`);
+	lines.push(
+		`process_metrics_sample_count ${averaged.sampleCount} ${timestamp}`,
+	);
 
 	return lines.join("\n");
 }
@@ -491,4 +500,4 @@ export async function collectMetrics(): Promise<RuntimeMetrics> {
 		eventLoopLag,
 		timestamp: new Date().toISOString(),
 	};
-}
+}