@bloomneo/appkit 1.2.9

package/dist/queue/transports/database.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Database queue transport using AppKit Prisma for persistent job storage
+ * @module @bloomneo/appkit/queue
+ * @file src/queue/transports/database.ts
+ *
+ * @llm-rule WHEN: Need persistent queuing with existing database - leverages AppKit database
+ * @llm-rule AVOID: When high-throughput needed - database polling has overhead
+ * @llm-rule NOTE: Uses existing Prisma client from AppKit, perfect for simple persistent queuing
+ */
+import type { Transport } from '../queue.js';
+import type { QueueConfig } from '../defaults.js';
+import type { JobData, JobOptions, JobHandler, QueueStats, JobInfo, JobStatus } from '../index.js';
+/**
+ * Database transport using AppKit Prisma for persistent storage
+ */
+export declare class DatabaseTransport implements Transport {
+    private config;
+    private db;
+    private handlers;
+    private paused;
+    private processing;
+    private processingLoop;
+    private cleanupTimer;
+    private healthCheckTimer;
+    /**
+     * Creates database transport using existing AppKit Prisma client
+     * @llm-rule WHEN: Auto-detected from DATABASE_URL with existing AppKit database
+     * @llm-rule AVOID: Manual database setup - leverages existing infrastructure
+     */
+    constructor(config: QueueConfig);
+    /**
+     * Initialize database transport
+     * @llm-rule WHEN: Transport creation - ensures table exists and starts processing
+     * @llm-rule AVOID: Calling manually - constructor handles initialization
+     */
+    private initialize;
+    /**
+     * Add job to database queue
+     * @llm-rule WHEN: Adding jobs for persistent background processing
+     * @llm-rule AVOID: Very high frequency - database has transaction overhead
+     */
+    add(id: string, jobType: string, data: JobData, options: JobOptions): Promise<void>;
+    /**
+     * Register job processor
+     * @llm-rule WHEN: Setting up job handlers for database-persisted jobs
+     * @llm-rule AVOID: Multiple handlers for same type - causes processing conflicts
+     */
+    process<T = JobData>(jobType: string, handler: JobHandler<T>): void;
+    /**
+     * Schedule job for future execution
+     * @llm-rule WHEN: Need persistent delayed job execution with database reliability
+     * @llm-rule AVOID: Very frequent scheduling - database writes have overhead
+     */
+    schedule(id: string, jobType: string, data: JobData, delay: number): Promise<void>;
+    /**
+     * Pause queue processing
+     * @llm-rule WHEN: Maintenance mode or controlled processing stop
+     * @llm-rule AVOID: Database-wide pausing - affects other application parts
+     */
+    pause(jobType?: string): Promise<void>;
+    /**
+     * Resume queue processing
+     * @llm-rule WHEN: Resuming after maintenance pause
+     * @llm-rule AVOID: Resuming without checking database health
+     */
+    resume(jobType?: string): Promise<void>;
+    /**
+     * Get queue statistics from database
+     * @llm-rule WHEN: Monitoring queue health and job status distribution
+     * @llm-rule AVOID: Frequent polling - database aggregation queries are expensive
+     */
+    getStats(jobType?: string): Promise<QueueStats>;
+    /**
+     * Get jobs by status from database
+     * @llm-rule WHEN: Debugging failed jobs or monitoring job history
+     * @llm-rule AVOID: Large result sets without pagination - database performance impact
+     */
+    getJobs(status: JobStatus, jobType?: string, limit?: number): Promise<JobInfo[]>;
+    /**
+     * Retry failed job in database
+     * @llm-rule WHEN: Manual retry of failed jobs from admin interface
+     * @llm-rule AVOID: Retrying without fixing underlying code issues
+     */
+    retry(jobId: string): Promise<void>;
+    /**
+     * Remove job from database
+     * @llm-rule WHEN: Canceling scheduled jobs or permanent cleanup
+     * @llm-rule AVOID: Removing active jobs - can cause worker inconsistencies
+     */
+    remove(jobId: string): Promise<void>;
+    /**
+     * Clean old jobs from database
+     * @llm-rule WHEN: Periodic cleanup to prevent database growth
+     * @llm-rule AVOID: Aggressive cleanup without considering audit requirements
+     */
+    clean(status: JobStatus, grace?: number): Promise<void>;
+    /**
+     * Get database transport health status
+     * @llm-rule WHEN: Health checks and monitoring
+     * @llm-rule AVOID: Complex health logic - database connection is main indicator
+     */
+    getHealth(): {
+        status: 'healthy' | 'degraded' | 'unhealthy';
+        message?: string;
+    };
+    /**
+     * Close database transport and cleanup resources
+     * @llm-rule WHEN: App shutdown or testing cleanup
+     * @llm-rule AVOID: Closing shared database connection - other parts of app use it
+     */
+    close(): Promise<void>;
+    /**
+     * Start background job processing
+     */
+    private startProcessing;
+    /**
+     * Main job processing loop
+     */
+    private processJobs;
+    /**
+     * Process waiting jobs up to concurrency limit
+     */
+    private processWaitingJobs;
+    /**
+     * Process individual job with database state management
+     */
+    private processJob;
+    /**
+     * Atomically claim job for processing
+     */
+    private claimJob;
+    /**
+     * Complete job successfully
+     */
+    private completeJob;
+    /**
+     * Fail job with retry logic
+     */
+    private failJob;
+    /**
+     * Calculate retry delay with backoff
+     */
+    private calculateRetryDelay;
+    /**
+     * Setup periodic cleanup
+     */
+    private setupCleanup;
+    /**
+     * Setup periodic health checks
+     */
+    private setupHealthCheck;
+    /**
+     * Ensure queue jobs table exists
+     */
+    private ensureTableExists;
+    /**
+     * Map JobStatus to database status
+     */
+    private mapStatusToDb;
+    /**
+     * Convert database job to JobInfo
+     */
+    private dbJobToInfo;
+}
+//# sourceMappingURL=database.d.ts.map

package/dist/queue/transports/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../src/queue/transports/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAqBnG;;GAEG;AACH,qBAAa,iBAAkB,YAAW,SAAS;IACjD,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,EAAE,CAAM;IAChB,OAAO,CAAC,QAAQ,CAAsC;IACtD,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,UAAU,CAAqB;IAGvC,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,gBAAgB,CAA+B;IAEvD;;;;OAIG;gBACS,MAAM,EAAE,WAAW;IAK/B;;;;OAIG;YACW,UAAU;IAiBxB;;;;OAIG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBzF;;;;OAIG;IACH,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;IAInE;;;;OAIG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBxF;;;;OAIG;IACG,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW5C;;;;OAIG;IACG,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7C;;;;OAIG;IACG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IA8BrD;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,GAAE,MAAY,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAuB3F;;;;OAIG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BzC;;;;OAIG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB1C;;;;OAIG;IACG,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,GAAE,MAA4B,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BlF;;;;OAIG;IACH,SAAS,IAAI;QAAE,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;IAU/E;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmC5B;;OAEG;IACH,OAAO,CAAC,eAAe;IAIvB;;OAEG;YACW,WAAW;IAWzB;;OAEG;YACW,kBAAkB;IAuChC;;OAEG;YACW,UAAU;IA0BxB;;OAEG;YACW,QAAQ;IAqBtB;;OAEG;YACW,WAAW;IAezB;;OAEG;YACW,OAAO;IAoCrB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAe3B;;OAEG;IACH,OAAO,CAAC,YAAY;IAepB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;OAEG;YACW,iBAAiB;IAkB/B;;OAEG;IACH,OAAO,CAAC,aAAa;IAarB;;OAEG;IACH,OAAO,CAAC,WAAW;CAwBpB"}