@bloomneo/appkit 1.2.9

package/dist/queue/queue.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Core queuing class with automatic transport management and job processing
+ * @module @bloomneo/appkit/queue
+ * @file src/queue/queue.ts
+ *
+ * @llm-rule WHEN: Building queue instances - called via queueClass.get(), not directly
+ * @llm-rule AVOID: Creating QueueClass directly - always use queueClass.get() for proper setup
+ * @llm-rule NOTE: Auto-detects and switches between Memory, Redis, Database transports
+ */
+import type { QueueConfig } from './defaults.js';
+import type { JobData, JobOptions, JobHandler, Queue, QueueStats, JobInfo, JobStatus } from './index.js';
+export interface Transport {
+    add(id: string, jobType: string, data: JobData, options: JobOptions): Promise<void>;
+    process(jobType: string, handler: JobHandler<JobData>): void;
+    schedule(id: string, jobType: string, data: JobData, delay: number): Promise<void>;
+    pause(jobType?: string): Promise<void>;
+    resume(jobType?: string): Promise<void>;
+    getStats(jobType?: string): Promise<QueueStats>;
+    getJobs(status: JobStatus, jobType?: string): Promise<JobInfo[]>;
+    retry(jobId: string): Promise<void>;
+    remove(jobId: string): Promise<void>;
+    clean(status: JobStatus, grace?: number): Promise<void>;
+    getHealth(): {
+        status: 'healthy' | 'degraded' | 'unhealthy';
+        message?: string;
+    };
+    close(): Promise<void>;
+}
+/**
+ * Core queuing class with automatic transport management
+ */
+export declare class QueueClass implements Queue {
+    private config;
+    private transport;
+    private transportType;
+    private isClosing;
+    constructor(config: QueueConfig);
+    /**
+     * Initialize transport based on configuration
+     * @llm-rule WHEN: QueueClass construction - sets up appropriate transport
+     * @llm-rule AVOID: Manual transport selection - config determines transport type
+     */
+    private initializeTransport;
+    /**
+     * Add job to queue with automatic ID generation and validation
+     * @llm-rule WHEN: Adding background jobs for processing
+     * @llm-rule AVOID: Direct transport calls - this handles ID generation and validation
+     */
+    add<T = JobData>(jobType: string, data: T, options?: JobOptions): Promise<string>;
+    /**
+     * Register job processor for specific job type
+     * @llm-rule WHEN: Setting up job handlers for background processing
+     * @llm-rule AVOID: Multiple processors for same job type - causes conflicts
+     */
+    process<T = JobData>(jobType: string, handler: JobHandler<T>): void;
+    /**
+     * Schedule job for future execution
+     * @llm-rule WHEN: Need to delay job execution (reminders, notifications, etc.)
+     * @llm-rule AVOID: Using setTimeout - this persists across app restarts
+     */
+    schedule<T = JobData>(jobType: string, data: T, delay: number): Promise<string>;
+    /**
+     * Pause queue processing
+     * @llm-rule WHEN: Maintenance mode or controlled shutdown
+     * @llm-rule AVOID: Pausing without resume plan - jobs will accumulate
+     */
+    pause(jobType?: string): Promise<void>;
+    /**
+     * Resume queue processing
+     * @llm-rule WHEN: Resuming after maintenance or pause
+     * @llm-rule AVOID: Resuming without checking system health
+     */
+    resume(jobType?: string): Promise<void>;
+    /**
+     * Get queue statistics for monitoring
+     * @llm-rule WHEN: Health checks, monitoring dashboards, debugging
+     * @llm-rule AVOID: Frequent polling - can be expensive for some transports
+     */
+    getStats(jobType?: string): Promise<QueueStats>;
+    /**
+     * Get jobs by status for debugging and monitoring
+     * @llm-rule WHEN: Debugging failed jobs or monitoring queue health
+     * @llm-rule AVOID: Getting large result sets - use pagination for big queues
+     */
+    getJobs(status: JobStatus, jobType?: string): Promise<JobInfo[]>;
+    /**
+     * Retry failed job by ID
+     * @llm-rule WHEN: Manual retry of failed jobs from admin interface
+     * @llm-rule AVOID: Retrying jobs that failed due to code errors without fixing code
+     */
+    retry(jobId: string): Promise<void>;
+    /**
+     * Remove job from queue
+     * @llm-rule WHEN: Canceling scheduled jobs or cleaning up specific jobs
+     * @llm-rule AVOID: Removing active jobs - let them complete naturally
+     */
+    remove(jobId: string): Promise<void>;
+    /**
+     * Clean old jobs by status
+     * @llm-rule WHEN: Periodic cleanup to prevent queue storage growth
+     * @llm-rule AVOID: Aggressive cleanup - keep some completed jobs for debugging
+     */
+    clean(status: JobStatus, grace?: number): Promise<void>;
+    /**
+     * Gracefully close queue and cleanup resources
+     * @llm-rule WHEN: App shutdown or testing cleanup
+     * @llm-rule AVOID: Abrupt shutdown - can cause job loss
+     */
+    close(): Promise<void>;
+    /**
+     * Get active transport type for debugging
+     * @llm-rule WHEN: Debugging transport selection or health checks
+     * @llm-rule AVOID: Using for business logic - transport is implementation detail
+     */
+    getActiveTransport(): string;
+    /**
+     * Check if specific transport is active
+     * @llm-rule WHEN: Feature detection based on transport capabilities
+     * @llm-rule AVOID: Complex transport-specific logic - keep handlers generic
+     */
+    hasTransport(name: string): boolean;
+    /**
+     * Get current configuration for debugging
+     * @llm-rule WHEN: Debugging configuration or health checks
+     * @llm-rule AVOID: Using for runtime decisions - config is set at startup
+     */
+    getConfig(): QueueConfig;
+    /**
+     * Get health status of queue system
+     * @llm-rule WHEN: Health checks or monitoring
+     * @llm-rule AVOID: Frequent health checks - can impact performance
+     */
+    getHealth(): {
+        status: 'healthy' | 'degraded' | 'unhealthy';
+        transport: string;
+        message?: string;
+    };
+    /**
+     * Wrap job handler with error handling and retry logic
+     */
+    private wrapHandler;
+    /**
+     * Wait for active jobs to complete with timeout
+     */
+    private waitForActiveJobs;
+    /**
+     * Setup graceful shutdown handlers
+     */
+    private setupGracefulShutdown;
+    private validateJobType;
+    private validateJobData;
+    private validateHandler;
+    private validateDelay;
+    private validateJobId;
+}
+//# sourceMappingURL=queue.d.ts.map

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

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

package/dist/queue/queue.js

@@ -0,0 +1,387 @@
+/**
+ * Core queuing class with automatic transport management and job processing
+ * @module @bloomneo/appkit/queue
+ * @file src/queue/queue.ts
+ *
+ * @llm-rule WHEN: Building queue instances - called via queueClass.get(), not directly
+ * @llm-rule AVOID: Creating QueueClass directly - always use queueClass.get() for proper setup
+ * @llm-rule NOTE: Auto-detects and switches between Memory, Redis, Database transports
+ */
+import { randomUUID } from 'crypto';
+import { MemoryTransport } from './transports/memory.js';
+import { RedisTransport } from './transports/redis.js';
+import { DatabaseTransport } from './transports/database.js';
+/**
+ * Core queuing class with automatic transport management
+ */
+export class QueueClass {
+    config;
+    transport;
+    transportType;
+    isClosing = false;
+    constructor(config) {
+        this.config = config;
+        this.transportType = config.transport;
+        this.transport = this.initializeTransport();
+        // Setup graceful shutdown
+        this.setupGracefulShutdown();
+    }
+    /**
+     * Initialize transport based on configuration
+     * @llm-rule WHEN: QueueClass construction - sets up appropriate transport
+     * @llm-rule AVOID: Manual transport selection - config determines transport type
+     */
+    initializeTransport() {
+        try {
+            switch (this.config.transport) {
+                case 'redis':
+                    if (!this.config.redis.url) {
+                        console.warn('Redis transport selected but REDIS_URL not available, falling back to memory');
+                        return new MemoryTransport(this.config);
+                    }
+                    return new RedisTransport(this.config);
+                case 'database':
+                    if (!this.config.database.url) {
+                        console.warn('Database transport selected but DATABASE_URL not available, falling back to memory');
+                        return new MemoryTransport(this.config);
+                    }
+                    return new DatabaseTransport(this.config);
+                case 'memory':
+                default:
+                    return new MemoryTransport(this.config);
+            }
+        }
+        catch (error) {
+            console.error(`Failed to initialize ${this.config.transport} transport:`, error.message);
+            console.log('Falling back to memory transport');
+            this.transportType = 'memory';
+            return new MemoryTransport(this.config);
+        }
+    }
+    /**
+     * Add job to queue with automatic ID generation and validation
+     * @llm-rule WHEN: Adding background jobs for processing
+     * @llm-rule AVOID: Direct transport calls - this handles ID generation and validation
+     */
+    async add(jobType, data, options = {}) {
+        this.validateJobType(jobType);
+        this.validateJobData(data);
+        const jobId = randomUUID();
+        const jobOptions = {
+            priority: options.priority ?? this.config.defaultPriority,
+            delay: options.delay ?? 0,
+            attempts: options.attempts ?? this.config.maxAttempts,
+            backoff: options.backoff ?? this.config.retryBackoff,
+            removeOnComplete: options.removeOnComplete ?? this.config.removeOnComplete,
+            removeOnFail: options.removeOnFail ?? this.config.removeOnFail,
+        };
+        try {
+            if (jobOptions.delay && jobOptions.delay > 0) {
+                await this.transport.schedule(jobId, jobType, data, jobOptions.delay);
+            }
+            else {
+                await this.transport.add(jobId, jobType, data, jobOptions);
+            }
+            return jobId;
+        }
+        catch (error) {
+            throw new Error(`Failed to add job: ${error.message}`);
+        }
+    }
+    /**
+     * Register job processor for specific job type
+     * @llm-rule WHEN: Setting up job handlers for background processing
+     * @llm-rule AVOID: Multiple processors for same job type - causes conflicts
+     */
+    process(jobType, handler) {
+        this.validateJobType(jobType);
+        this.validateHandler(handler);
+        // Wrap handler with error handling and retry logic
+        const wrappedHandler = this.wrapHandler(handler);
+        try {
+            this.transport.process(jobType, wrappedHandler);
+        }
+        catch (error) {
+            throw new Error(`Failed to register processor for ${jobType}: ${error.message}`);
+        }
+    }
+    /**
+     * Schedule job for future execution
+     * @llm-rule WHEN: Need to delay job execution (reminders, notifications, etc.)
+     * @llm-rule AVOID: Using setTimeout - this persists across app restarts
+     */
+    async schedule(jobType, data, delay) {
+        this.validateJobType(jobType);
+        this.validateJobData(data);
+        this.validateDelay(delay);
+        const jobId = randomUUID();
+        try {
+            await this.transport.schedule(jobId, jobType, data, delay);
+            return jobId;
+        }
+        catch (error) {
+            throw new Error(`Failed to schedule job: ${error.message}`);
+        }
+    }
+    /**
+     * Pause queue processing
+     * @llm-rule WHEN: Maintenance mode or controlled shutdown
+     * @llm-rule AVOID: Pausing without resume plan - jobs will accumulate
+     */
+    async pause(jobType) {
+        try {
+            await this.transport.pause(jobType);
+        }
+        catch (error) {
+            throw new Error(`Failed to pause queue: ${error.message}`);
+        }
+    }
+    /**
+     * Resume queue processing
+     * @llm-rule WHEN: Resuming after maintenance or pause
+     * @llm-rule AVOID: Resuming without checking system health
+     */
+    async resume(jobType) {
+        try {
+            await this.transport.resume(jobType);
+        }
+        catch (error) {
+            throw new Error(`Failed to resume queue: ${error.message}`);
+        }
+    }
+    /**
+     * Get queue statistics for monitoring
+     * @llm-rule WHEN: Health checks, monitoring dashboards, debugging
+     * @llm-rule AVOID: Frequent polling - can be expensive for some transports
+     */
+    async getStats(jobType) {
+        try {
+            return await this.transport.getStats(jobType);
+        }
+        catch (error) {
+            throw new Error(`Failed to get stats: ${error.message}`);
+        }
+    }
+    /**
+     * Get jobs by status for debugging and monitoring
+     * @llm-rule WHEN: Debugging failed jobs or monitoring queue health
+     * @llm-rule AVOID: Getting large result sets - use pagination for big queues
+     */
+    async getJobs(status, jobType) {
+        try {
+            return await this.transport.getJobs(status, jobType);
+        }
+        catch (error) {
+            throw new Error(`Failed to get jobs: ${error.message}`);
+        }
+    }
+    /**
+     * Retry failed job by ID
+     * @llm-rule WHEN: Manual retry of failed jobs from admin interface
+     * @llm-rule AVOID: Retrying jobs that failed due to code errors without fixing code
+     */
+    async retry(jobId) {
+        this.validateJobId(jobId);
+        try {
+            await this.transport.retry(jobId);
+        }
+        catch (error) {
+            throw new Error(`Failed to retry job ${jobId}: ${error.message}`);
+        }
+    }
+    /**
+     * Remove job from queue
+     * @llm-rule WHEN: Canceling scheduled jobs or cleaning up specific jobs
+     * @llm-rule AVOID: Removing active jobs - let them complete naturally
+     */
+    async remove(jobId) {
+        this.validateJobId(jobId);
+        try {
+            await this.transport.remove(jobId);
+        }
+        catch (error) {
+            throw new Error(`Failed to remove job ${jobId}: ${error.message}`);
+        }
+    }
+    /**
+     * Clean old jobs by status
+     * @llm-rule WHEN: Periodic cleanup to prevent queue storage growth
+     * @llm-rule AVOID: Aggressive cleanup - keep some completed jobs for debugging
+     */
+    async clean(status, grace = 24 * 60 * 60 * 1000) {
+        try {
+            await this.transport.clean(status, grace);
+        }
+        catch (error) {
+            throw new Error(`Failed to clean ${status} jobs: ${error.message}`);
+        }
+    }
+    /**
+     * Gracefully close queue and cleanup resources
+     * @llm-rule WHEN: App shutdown or testing cleanup
+     * @llm-rule AVOID: Abrupt shutdown - can cause job loss
+     */
+    async close() {
+        if (this.isClosing) {
+            return; // Already closing
+        }
+        this.isClosing = true;
+        try {
+            // Pause processing first
+            await this.transport.pause();
+            // Wait for current jobs to complete (with timeout)
+            await this.waitForActiveJobs();
+            // Close transport
+            await this.transport.close();
+        }
+        catch (error) {
+            console.error('Error during graceful shutdown:', error.message);
+        }
+    }
+    /**
+     * Get active transport type for debugging
+     * @llm-rule WHEN: Debugging transport selection or health checks
+     * @llm-rule AVOID: Using for business logic - transport is implementation detail
+     */
+    getActiveTransport() {
+        return this.transportType;
+    }
+    /**
+     * Check if specific transport is active
+     * @llm-rule WHEN: Feature detection based on transport capabilities
+     * @llm-rule AVOID: Complex transport-specific logic - keep handlers generic
+     */
+    hasTransport(name) {
+        return this.transportType === name;
+    }
+    /**
+     * Get current configuration for debugging
+     * @llm-rule WHEN: Debugging configuration or health checks
+     * @llm-rule AVOID: Using for runtime decisions - config is set at startup
+     */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Get health status of queue system
+     * @llm-rule WHEN: Health checks or monitoring
+     * @llm-rule AVOID: Frequent health checks - can impact performance
+     */
+    getHealth() {
+        try {
+            const transportHealth = this.transport.getHealth();
+            return {
+                ...transportHealth,
+                transport: this.transportType,
+            };
+        }
+        catch (error) {
+            return {
+                status: 'unhealthy',
+                transport: this.transportType,
+                message: `Health check failed: ${error.message}`,
+            };
+        }
+    }
+    // ============================================================================
+    // PRIVATE HELPER METHODS
+    // ============================================================================
+    /**
+     * Wrap job handler with error handling and retry logic
+     */
+    wrapHandler(handler) {
+        return async (data) => {
+            try {
+                const result = await handler(data);
+                return result;
+            }
+            catch (error) {
+                // Re-throw error for transport to handle retry logic
+                throw error;
+            }
+        };
+    }
+    /**
+     * Wait for active jobs to complete with timeout
+     */
+    async waitForActiveJobs() {
+        const timeout = this.config.worker.gracefulShutdownTimeout;
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeout) {
+            try {
+                const stats = await this.transport.getStats();
+                if (stats.active === 0) {
+                    return; // No active jobs
+                }
+                // Wait a bit before checking again
+                await new Promise(resolve => setTimeout(resolve, 1000));
+            }
+            catch (error) {
+                // If we can't check stats, just wait the timeout
+                break;
+            }
+        }
+        console.warn(`Graceful shutdown timeout (${timeout}ms) exceeded, forcing close`);
+    }
+    /**
+     * Setup graceful shutdown handlers
+     */
+    setupGracefulShutdown() {
+        const handleShutdown = async (signal) => {
+            console.log(`Received ${signal}, starting graceful shutdown...`);
+            await this.close();
+            process.exit(0);
+        };
+        process.once('SIGTERM', () => handleShutdown('SIGTERM'));
+        process.once('SIGINT', () => handleShutdown('SIGINT'));
+    }
+    // ============================================================================
+    // VALIDATION METHODS
+    // ============================================================================
+    validateJobType(jobType) {
+        if (!jobType || typeof jobType !== 'string') {
+            throw new Error('Job type must be a non-empty string');
+        }
+        if (jobType.length > 100) {
+            throw new Error('Job type must be 100 characters or less');
+        }
+        if (!/^[a-zA-Z0-9_-]+$/.test(jobType)) {
+            throw new Error('Job type can only contain letters, numbers, underscores, and hyphens');
+        }
+    }
+    validateJobData(data) {
+        if (data === null || data === undefined) {
+            throw new Error('Job data cannot be null or undefined');
+        }
+        try {
+            JSON.stringify(data);
+        }
+        catch (error) {
+            throw new Error('Job data must be JSON serializable');
+        }
+    }
+    validateHandler(handler) {
+        if (typeof handler !== 'function') {
+            throw new Error('Job handler must be a function');
+        }
+    }
+    validateDelay(delay) {
+        if (typeof delay !== 'number' || delay < 0) {
+            throw new Error('Delay must be a positive number (milliseconds)');
+        }
+        if (delay > 365 * 24 * 60 * 60 * 1000) {
+            throw new Error('Delay cannot exceed 1 year');
+        }
+    }
+    validateJobId(jobId) {
+        if (!jobId || typeof jobId !== 'string') {
+            throw new Error('Job ID must be a non-empty string');
+        }
+        // Validate UUID format
+        const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+        if (!uuidRegex.test(jobId)) {
+            throw new Error('Job ID must be a valid UUID');
+        }
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/queue/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../src/queue/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAmB7D;;GAEG;AACH,MAAM,OAAO,UAAU;IACb,MAAM,CAAc;IACpB,SAAS,CAAY;IACrB,aAAa,CAAS;IACtB,SAAS,GAAG,KAAK,CAAC;IAE1B,YAAY,MAAmB;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC,SAAS,CAAC;QACtC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAE5C,0BAA0B;QAC1B,IAAI,CAAC,qBAAqB,EAAE,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACK,mBAAmB;QACzB,IAAI,CAAC;YACH,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;gBAC9B,KAAK,OAAO;oBACV,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;wBAC3B,OAAO,CAAC,IAAI,CAAC,8EAA8E,CAAC,CAAC;wBAC7F,OAAO,IAAI,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;oBAC1C,CAAC;oBACD,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAEzC,KAAK,UAAU;oBACb,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC;wBAC9B,OAAO,CAAC,IAAI,CAAC,oFAAoF,CAAC,CAAC;wBACnG,OAAO,IAAI,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;oBAC1C,CAAC;oBACD,OAAO,IAAI,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAE5C,KAAK,QAAQ,CAAC;gBACd;oBACE,OAAO,IAAI,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC5C,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,wBAAwB,IAAI,CAAC,MAAM,CAAC,SAAS,aAAa,EAAG,KAAe,CAAC,OAAO,CAAC,CAAC;YACpG,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;YAChD,IAAI,CAAC,aAAa,GAAG,QAAQ,CAAC;YAC9B,OAAO,IAAI,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAG,CAAc,OAAe,EAAE,IAAO,EAAE,UAAsB,EAAE;QACvE,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QAC9B,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QAE3B,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;QAC3B,MAAM,UAAU,GAAe;YAC7B,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,eAAe;YACzD,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;YACzB,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW;YACrD,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY;YACpD,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,IAAI,CAAC,MAAM,CAAC,gBAAgB;YAC1E,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY;SAC/D,CAAC;QAEF,IAAI,CAAC;YACH,IAAI,UAAU,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;gBAC7C,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,IAAe,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;YACnF,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,IAAe,EAAE,UAAU,CAAC,CAAC;YACxE,CAAC;YAED,OAAO,KAAK,CAAC;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,sBAAuB,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAc,OAAe,EAAE,OAAsB;QAC1D,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QAC9B,IAAI,CAAC,eAAe,CAAC,OAA0B,CAAC,CAAC;QAEjD,mDAAmD;QACnD,MAAM,cAAc,GAAG,IAAI,CAAC,WAAW,CAAI,OAAO,CAAC,CAAC;QAEpD,IAAI,CAAC;YACD,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,cAAqC,CAAC,CAAC;QAC3E,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,oCAAoC,OAAO,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QAChG,CAAC;IACD,CAAC;IAEH;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAc,OAAe,EAAE,IAAO,EAAE,KAAa;QACjE,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QAC9B,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAE1B,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;QAE3B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,IAAe,EAAE,KAAK,CAAC,CAAC;YACtE,OAAO,KAAK,CAAC;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,2BAA4B,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,OAAgB;QAC1B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,0BAA2B,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAM,CAAC,OAAgB;QAC3B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACvC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,2BAA4B,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAC,OAAgB;QAC7B,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAChD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,wBAAyB,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,MAAiB,EAAE,OAAgB;QAC/C,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACvD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,uBAAwB,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,KAAa;QACvB,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAE1B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,uBAAuB,KAAK,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAM,CAAC,KAAa;QACxB,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAE1B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,wBAAwB,KAAK,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QAChF,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,MAAiB,EAAE,QAAgB,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;QAChE,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC5C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,UAAW,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QACjF,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,OAAO,CAAC,kBAAkB;QAC5B,CAAC;QAED,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QAEtB,IAAI,CAAC;YACH,yBAAyB;YACzB,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;YAE7B,mDAAmD;YACnD,MAAM,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAE/B,kBAAkB;YAClB,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QAC/B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,iCAAiC,EAAG,KAAe,CAAC,OAAO,CAAC,CAAC;QAC7E,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,kBAAkB;QAChB,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACH,YAAY,CAAC,IAAY;QACvB,OAAO,IAAI,CAAC,aAAa,KAAK,IAAI,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACH,SAAS;QACP,IAAI,CAAC;YACH,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,CAAC;YACnD,OAAO;gBACL,GAAG,eAAe;gBAClB,SAAS,EAAE,IAAI,CAAC,aAAa;aAC9B,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO;gBACL,MAAM,EAAE,WAAW;gBACnB,SAAS,EAAE,IAAI,CAAC,aAAa;gBAC7B,OAAO,EAAE,wBAAyB,KAAe,CAAC,OAAO,EAAE;aAC5D,CAAC;QACJ,CAAC;IACH,CAAC;IAED,+EAA+E;IAC/E,yBAAyB;IACzB,+EAA+E;IAE/E;;OAEG;IACK,WAAW,CAAc,OAAsB;QACrD,OAAO,KAAK,EAAE,IAAO,EAAgB,EAAE;YACrC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;gBACnC,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,qDAAqD;gBACrD,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,iBAAiB;QAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,uBAAuB,CAAC;QAC3D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,OAAO,EAAE,CAAC;YACxC,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC;gBAC9C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACvB,OAAO,CAAC,iBAAiB;gBAC3B,CAAC;gBAED,mCAAmC;gBACnC,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;YAC1D,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,iDAAiD;gBACjD,MAAM;YACR,CAAC;QACH,CAAC;QAED,OAAO,CAAC,IAAI,CAAC,8BAA8B,OAAO,6BAA6B,CAAC,CAAC;IACnF,CAAC;IAED;;OAEG;IACK,qBAAqB;QAC3B,MAAM,cAAc,GAAG,KAAK,EAAE,MAAc,EAAE,EAAE;YAC9C,OAAO,CAAC,GAAG,CAAC,YAAY,MAAM,iCAAiC,CAAC,CAAC;YACjE,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;YACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC,CAAC;QAEF,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC;QACzD,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;IACzD,CAAC;IAED,+EAA+E;IAC/E,qBAAqB;IACrB,+EAA+E;IAEvE,eAAe,CAAC,OAAe;QACrC,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;QACzD,CAAC;QAED,IAAI,OAAO,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QAC7D,CAAC;QAED,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;QAC1F,CAAC;IACH,CAAC;IAEO,eAAe,CAAC,IAAS;QAC/B,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;QAC1D,CAAC;QAED,IAAI,CAAC;YACH,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAEO,eAAe,CAAC,OAAmB;QACzC,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IAEO,aAAa,CAAC,KAAa;QACjC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QAED,IAAI,KAAK,GAAG,GAAG,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAEO,aAAa,CAAC,KAAa;QACjC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvD,CAAC;QAED,uBAAuB;QACvB,MAAM,SAAS,GAAG,iEAAiE,CAAC;QACpF,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;CACF"}