@buenojs/bueno 0.8.10 → 0.8.11

package/dist/jobs/queue.js

@@ -0,0 +1,233 @@
+/**
+ * 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";
+// ============= Job Queue Class =============
+export class JobQueue {
+    driver;
+    handlers = new Map();
+    handlerRegistry = [];
+    eventListeners = new Map();
+    isRunning = false;
+    constructor(config = {}) {
+        // 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() {
+        await this.driver.connect();
+    }
+    /**
+     * Shutdown the queue gracefully
+     */
+    async shutdown() {
+        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(name, data, options) {
+        const jobId = await this.driver.enqueue(name, data, options);
+        this._emitEvent("enqueued", { id: jobId, name });
+        return jobId;
+    }
+    /**
+     * Register a handler for a job type
+     * Supports wildcards: "email.*" matches "email.welcome", "email.reset", etc.
+     */
+    on(pattern, handler) {
+        this.handlers.set(pattern, handler);
+        // Calculate specificity for wildcard matching (longer = more specific)
+        const specificity = pattern.split(".").length;
+        const entry = { 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) {
+        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
+     */
+    findHandler(jobName) {
+        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)
+     */
+    _patternMatches(pattern, jobName) {
+        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, listener) {
+        if (!this.eventListeners.has(event)) {
+            this.eventListeners.set(event, new Set());
+        }
+        this.eventListeners.get(event).add(listener);
+    }
+    /**
+     * Stop listening for queue events
+     */
+    offEvent(event, listener) {
+        this.eventListeners.get(event)?.delete(listener);
+    }
+    /**
+     * Emit a queue event
+     */
+    _emitEvent(eventType, job) {
+        const listeners = this.eventListeners.get(eventType);
+        if (!listeners)
+            return;
+        const event = {
+            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 = {}) {
+        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() {
+        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) {
+        return this.driver.getJob(jobId);
+    }
+    /**
+     * Get queue metrics
+     */
+    async getMetrics() {
+        return this.driver.getMetrics();
+    }
+    /**
+     * Clear all jobs (use with caution!)
+     */
+    async clear() {
+        return this.driver.clear();
+    }
+    /**
+     * Check if queue is connected
+     */
+    async isConnected() {
+        return this.driver.isConnected();
+    }
+}
+// ============= Factory Function =============
+/**
+ * Create a new job queue instance
+ */
+export function createJobQueue(config) {
+    return new JobQueue(config);
+}
+//# sourceMappingURL=queue.js.map

package/dist/jobs/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../src/jobs/queue.ts"],"names":[],"mappings":"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"}

package/dist/jobs/types.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Background Jobs / Task Queue
+ *
+ * Type definitions for the job queue system.
+ * Supports Redis (production) and in-memory (development) drivers.
+ */
+export type JobStatus = "pending" | "processing" | "completed" | "failed" | "delayed";
+/**
+ * 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;
+}
+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;
+}
+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;
+}
+/**
+ * Async handler function for processing jobs
+ */
+export type JobHandler<T = unknown> = (job: Job<T>) => Promise<void>;
+/**
+ * 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;
+}
+export type JobEventType = "enqueued" | "started" | "completed" | "failed" | "retried";
+export interface JobEvent<T = unknown> {
+    type: JobEventType;
+    job: Job<T>;
+    timestamp: Date;
+    metadata?: Record<string, unknown>;
+}
+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;
+}
+/**
+ * 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>;
+}
+export interface HandlerRegistryEntry {
+    pattern: string;
+    handler: JobHandler<unknown>;
+    specificity: number;
+}
+export interface JobConfigValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/jobs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/jobs/types.ts"],"names":[],"mappings":"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"}

package/dist/jobs/types.js

@@ -0,0 +1,8 @@
+/**
+ * Background Jobs / Task Queue
+ *
+ * Type definitions for the job queue system.
+ * Supports Redis (production) and in-memory (development) drivers.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/jobs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/jobs/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/jobs/worker.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 type { JobEvent, JobEventType, JobHandler, JobQueueConfig } from "./types";
+export declare class JobWorker {
+    private driver;
+    private handlers;
+    private handlerRegistry;
+    private eventListeners;
+    private isRunning;
+    private pollInterval;
+    private concurrency;
+    private jobTimeout;
+    private maxBackoffDelay;
+    private currentBackoff;
+    private inFlightJobs;
+    private shutdownTimeout;
+    constructor(config?: JobQueueConfig);
+    /**
+     * Initialize the worker (connect to backend)
+     */
+    init(): Promise<void>;
+    /**
+     * Register a handler for a job type
+     * Supports wildcards: "email.*" matches "email.welcome", "email.reset", etc.
+     */
+    handle(pattern: string, handler: JobHandler<unknown>): void;
+    /**
+     * Remove a handler
+     */
+    unhandle(pattern: string): void;
+    /**
+     * Listen for worker events
+     */
+    on(eventType: JobEventType, listener: (event: JobEvent) => void): void;
+    /**
+     * Stop listening for events
+     */
+    off(eventType: JobEventType, listener: (event: JobEvent) => void): void;
+    /**
+     * Emit a worker event
+     */
+    private _emitEvent;
+    /**
+     * Find the best matching handler for a job
+     */
+    private findHandler;
+    /**
+     * Check if a pattern matches a job name (supports wildcards)
+     */
+    private _patternMatches;
+    /**
+     * Start the worker (blocks until stopped)
+     */
+    start(): Promise<void>;
+    /**
+     * Main polling loop
+     */
+    private _pollLoop;
+    /**
+     * Process a single job
+     */
+    private _processJob;
+    /**
+     * Stop the worker gracefully
+     * Waits for in-flight jobs to complete before shutdown
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the number of jobs currently being processed
+     */
+    getInFlightCount(): number;
+    /**
+     * Get queue metrics
+     */
+    getMetrics(): Promise<import("./types").QueueMetrics>;
+    /**
+     * Check if worker is running
+     */
+    isActive(): boolean;
+}
+/**
+ * Create and start a worker from config
+ * Useful for CLI commands like: bueno queue:worker
+ */
+export declare function startWorker(config?: JobQueueConfig): Promise<void>;
+//# sourceMappingURL=worker.d.ts.map

package/dist/jobs/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/jobs/worker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAGX,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,cAAc,EAEd,MAAM,SAAS,CAAC;AAIjB,qBAAa,SAAS;IACrB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,eAAe,CAA8B;IACrD,OAAO,CAAC,cAAc,CACX;IACX,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,eAAe,CAAS;gBAEpB,MAAM,GAAE,cAAmB;IAkBvC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,IAAI;IAkB3D;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQ/B;;OAEG;IACH,EAAE,CAAC,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI;IAOtE;;OAEG;IACH,GAAG,CAAC,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI;IAIvE;;OAEG;IACH,OAAO,CAAC,UAAU;IAmBlB;;OAEG;IACH,OAAO,CAAC,WAAW;IASnB;;OAEG;IACH,OAAO,CAAC,eAAe;IAYvB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB5B;;OAEG;YACW,SAAS;IAiDvB;;OAEG;YACW,WAAW;IAyDzB;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA0B3B;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACG,UAAU;IAIhB;;OAEG;IACH,QAAQ,IAAI,OAAO;CAGnB;AAID;;;GAGG;AACH,wBAAsB,WAAW,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBxE"}