@riktajs/queue 0.10.2 → 0.10.3

package/dist/index.d.ts

@@ -1,22 +1,946 @@
+import { QueueOptions, JobsOptions, WorkerOptions, RepeatOptions, Queue as Queue$1, Job } from 'bullmq';
+export { Queue as BullQueue, Job, QueueEvents, Worker } from 'bullmq';
+import { z, ZodSchema, ZodError } from 'zod';
+export { z } from 'zod';
+import { OnProviderInit, OnProviderDestroy } from '@riktajs/core';
+import { FastifyRequest, FastifyInstance } from 'fastify';
+import { Redis, Cluster } from 'ioredis';
+export { Redis } from 'ioredis';
+
 /**
- * @riktajs/queue
- *
- * BullMQ-based job queue integration for Rikta Framework.
- *
- * @packageDocumentation
- */
-export * from './constants.js';
-export * from './types.js';
-export * from './config/queue.config.js';
-export { Queue, getQueueOptions, isQueue, QueueDecoratorError, } from './decorators/queue.decorator.js';
-export { Processor, getProcessorOptions, isProcessor, ProcessorDecoratorError, } from './decorators/processor.decorator.js';
-export { Process, getJobHandlers, isJobHandler, } from './decorators/process.decorator.js';
-export { OnJobComplete, OnJobFailed, OnJobProgress, OnJobStalled, OnWorkerReady, OnWorkerError, getEventHandlers, getEventHandlersFor, } from './decorators/events.decorator.js';
-export * from './providers/queue.provider.js';
-export * from './services/queue.service.js';
-export { QUEUE_EVENTS, getEventBusEventName, publishQueueEvent, } from './events/queue-events.js';
-export type { QueueEventName } from './events/queue-events.js';
-export * from './monitoring/bull-board.js';
-export * from './utils/connection.js';
-export * from './utils/validation.js';
-//# sourceMappingURL=index.d.ts.map
+ * Constants and DI tokens for @riktajs/queue
+ */
+/** Metadata keys for decorator reflection */
+declare const METADATA_KEY: {
+    /** Queue class decorator options */
+    readonly QUEUE_OPTIONS: "riktajs:queue:options";
+    /** Processor class decorator options */
+    readonly PROCESSOR_OPTIONS: "riktajs:queue:processor:options";
+    /** Job handler method metadata */
+    readonly JOB_HANDLERS: "riktajs:queue:job:handlers";
+    /** Event handler method metadata */
+    readonly EVENT_HANDLERS: "riktajs:queue:event:handlers";
+};
+/** DI token for the QueueProvider */
+declare const QUEUE_PROVIDER: unique symbol;
+/** DI token for the QueueService */
+declare const QUEUE_SERVICE: unique symbol;
+/** DI token for the Redis connection */
+declare const QUEUE_REDIS_CONNECTION: unique symbol;
+/** DI token for the queue configuration */
+declare const QUEUE_CONFIG: unique symbol;
+/**
+ * Get the DI token for a named queue
+ * @param name - The queue name
+ */
+declare function getQueueToken(name: string): symbol;
+/**
+ * Get the DI token for a named worker
+ * @param name - The queue name
+ */
+declare function getWorkerToken(name: string): symbol;
+
+/**
+ * Type definitions for @riktajs/queue
+ */
+
+/** Redis connection configuration */
+interface RedisConnectionOptions {
+    /** Redis host */
+    host?: string;
+    /** Redis port */
+    port?: number;
+    /** Redis password */
+    password?: string;
+    /** Redis username */
+    username?: string;
+    /** Redis database number */
+    db?: number;
+    /** Enable TLS */
+    tls?: boolean;
+    /** Cluster mode configuration */
+    cluster?: {
+        nodes: Array<{
+            host: string;
+            port: number;
+        }>;
+    };
+}
+/** Options for @Queue decorator */
+interface QueueDecoratorOptions {
+    /** Queue name (required) */
+    name: string;
+    /** BullMQ queue options */
+    options?: Omit<QueueOptions, 'connection'>;
+    /** Default job options */
+    defaultJobOptions?: JobsOptions;
+}
+/** Options for @Processor decorator */
+interface ProcessorOptions {
+    /** The queue name to process */
+    queueName: string;
+    /** Worker concurrency */
+    concurrency?: number;
+    /** Rate limiter configuration */
+    rateLimiter?: {
+        /** Maximum jobs per duration */
+        max: number;
+        /** Duration in milliseconds */
+        duration: number;
+    };
+    /** Additional BullMQ worker options */
+    workerOptions?: Omit<WorkerOptions, 'connection' | 'concurrency' | 'limiter'>;
+}
+/** Metadata for a job handler method */
+interface JobHandlerMeta {
+    /** Job name */
+    name: string;
+    /** Method name on the processor class */
+    methodName: string;
+    /** Validation schema (Zod) */
+    schema?: unknown;
+}
+/** Queue event names */
+type QueueEventName$1 = 'job:added' | 'job:completed' | 'job:failed' | 'job:progress' | 'job:stalled' | 'job:delayed' | 'job:removed' | 'worker:ready' | 'worker:closed' | 'worker:error';
+/** Metadata for an event handler method */
+interface EventHandlerMeta {
+    /** Event name */
+    event: QueueEventName$1;
+    /** Method name on the processor class */
+    methodName: string;
+}
+/** Event payload for queue events */
+interface QueueEventPayload<TData = unknown, TResult = unknown> {
+    /** Queue name */
+    queueName: string;
+    /** Job ID */
+    jobId: string;
+    /** Job name */
+    jobName: string;
+    /** Job data */
+    data: TData;
+    /** Job return value (for completed events) */
+    returnValue?: TResult;
+    /** Number of attempts made */
+    attemptsMade?: number;
+    /** Error message (for failed events) */
+    error?: string;
+    /** Progress value (for progress events) */
+    progress?: number | object;
+    /** Timestamp */
+    timestamp: number;
+}
+/** Options for adding a job */
+interface AddJobOptions extends JobsOptions {
+    /** Deduplicate by this key */
+    deduplicationKey?: string;
+}
+/** Repeat options for scheduled jobs */
+interface ScheduleOptions extends RepeatOptions {
+    /** Job ID for the repeatable job */
+    jobId?: string;
+}
+/** Queue configuration from environment/config */
+interface QueueConfig {
+    /** Redis connection options */
+    redis: RedisConnectionOptions;
+    /** Default worker concurrency */
+    defaultConcurrency?: number;
+    /** Default rate limiter */
+    defaultRateLimiter?: {
+        max: number;
+        duration: number;
+    };
+    /** Bull Board dashboard path */
+    dashboardPath?: string;
+    /** Enable dashboard (default: false in production) */
+    dashboardEnabled?: boolean;
+    /** Graceful shutdown timeout in ms */
+    shutdownTimeout?: number;
+}
+/** Provider options for creating QueueProvider */
+interface QueueProviderOptions {
+    /** Queue configuration */
+    config?: Partial<QueueConfig>;
+    /** Auto-initialize on provider init */
+    autoInitialize?: boolean;
+    /** Retry connection attempts */
+    retryAttempts?: number;
+    /** Delay between retries in ms */
+    retryDelay?: number;
+}
+
+/**
+ * Queue configuration schema and loader
+ */
+
+/** Zod schema for queue configuration */
+declare const QueueConfigSchema: z.ZodObject<{
+    redis: z.ZodObject<{
+        host: z.ZodDefault<z.ZodString>;
+        port: z.ZodDefault<z.ZodNumber>;
+        password: z.ZodOptional<z.ZodString>;
+        db: z.ZodDefault<z.ZodNumber>;
+        username: z.ZodOptional<z.ZodString>;
+        tls: z.ZodOptional<z.ZodBoolean>;
+        cluster: z.ZodOptional<z.ZodObject<{
+            nodes: z.ZodArray<z.ZodObject<{
+                host: z.ZodString;
+                port: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    defaultConcurrency: z.ZodDefault<z.ZodNumber>;
+    defaultRateLimiter: z.ZodOptional<z.ZodObject<{
+        max: z.ZodNumber;
+        duration: z.ZodNumber;
+    }, z.core.$strip>>;
+    dashboardPath: z.ZodDefault<z.ZodString>;
+    dashboardEnabled: z.ZodDefault<z.ZodBoolean>;
+    shutdownTimeout: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type QueueConfigInput = z.input<typeof QueueConfigSchema>;
+/**
+ * Load queue configuration from environment variables
+ * @param overrides - Optional configuration overrides
+ */
+declare function loadQueueConfig(overrides?: Partial<QueueConfigInput>): QueueConfig;
+/**
+ * Error thrown when queue configuration is invalid
+ */
+declare class QueueConfigError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * @Queue decorator - marks a class as a queue definition
+ */
+
+/**
+ * Decorator to define a queue
+ *
+ * @param options - Queue configuration options
+ * @returns ClassDecorator
+ *
+ * @example
+ * ```typescript
+ * @Queue({ name: 'email-queue' })
+ * class EmailQueue {}
+ * ```
+ */
+declare function Queue(options: QueueDecoratorOptions): ClassDecorator;
+/**
+ * Get queue options from a decorated class
+ * @param target - The decorated class
+ */
+declare function getQueueOptions(target: Function): QueueDecoratorOptions | undefined;
+/**
+ * Check if a class is decorated with @Queue
+ * @param target - The class to check
+ */
+declare function isQueue(target: Function): boolean;
+/**
+ * Error thrown when @Queue decorator is used incorrectly
+ */
+declare class QueueDecoratorError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * @Processor decorator - marks a class as a job processor
+ */
+
+/**
+ * Decorator to define a job processor for a queue
+ *
+ * @param queueName - The name of the queue to process
+ * @param options - Optional processor configuration
+ * @returns ClassDecorator
+ *
+ * @example
+ * ```typescript
+ * @Processor('email-queue', { concurrency: 5 })
+ * class EmailProcessor {
+ *   @Process('send')
+ *   async handleSendEmail(job: Job) {
+ *     // process job
+ *   }
+ * }
+ * ```
+ */
+declare function Processor(queueName: string, options?: Omit<ProcessorOptions, 'queueName'>): ClassDecorator;
+/**
+ * Get processor options from a decorated class
+ * @param target - The decorated class
+ */
+declare function getProcessorOptions(target: Function): ProcessorOptions | undefined;
+/**
+ * Check if a class is decorated with @Processor
+ * @param target - The class to check
+ */
+declare function isProcessor(target: Function): boolean;
+/**
+ * Error thrown when @Processor decorator is used incorrectly
+ */
+declare class ProcessorDecoratorError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * @Process decorator - marks a method as a job handler
+ */
+
+/**
+ * Decorator to define a job handler method
+ *
+ * @param jobName - The name of the job to handle (default: method name)
+ * @returns MethodDecorator
+ *
+ * @example
+ * ```typescript
+ * @Processor('email-queue')
+ * class EmailProcessor {
+ *   @Process('send')
+ *   async handleSendEmail(job: Job<EmailData>) {
+ *     await sendEmail(job.data);
+ *     return { sent: true };
+ *   }
+ *
+ *   @Process() // Uses method name as job name
+ *   async welcome(job: Job<WelcomeData>) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+declare function Process(jobName?: string): MethodDecorator;
+/**
+ * Get all job handlers from a processor class
+ * @param target - The processor class
+ */
+declare function getJobHandlers(target: Function): JobHandlerMeta[];
+/**
+ * Check if a method is decorated with @Process
+ * @param target - The class
+ * @param methodName - The method name
+ */
+declare function isJobHandler(target: Function, methodName: string): boolean;
+
+/**
+ * Event decorators for job lifecycle events
+ */
+
+/**
+ * Decorator for handling job completion events
+ *
+ * @example
+ * ```typescript
+ * @Processor('my-queue')
+ * class MyProcessor {
+ *   @OnJobComplete()
+ *   async handleComplete(job: Job, result: unknown) {
+ *     console.log(`Job ${job.id} completed with:`, result);
+ *   }
+ * }
+ * ```
+ */
+declare function OnJobComplete(): MethodDecorator;
+/**
+ * Decorator for handling job failure events
+ *
+ * @example
+ * ```typescript
+ * @Processor('my-queue')
+ * class MyProcessor {
+ *   @OnJobFailed()
+ *   async handleFailed(job: Job, error: Error) {
+ *     console.error(`Job ${job.id} failed:`, error);
+ *   }
+ * }
+ * ```
+ */
+declare function OnJobFailed(): MethodDecorator;
+/**
+ * Decorator for handling job progress events
+ *
+ * @example
+ * ```typescript
+ * @Processor('my-queue')
+ * class MyProcessor {
+ *   @OnJobProgress()
+ *   async handleProgress(job: Job, progress: number | object) {
+ *     console.log(`Job ${job.id} progress:`, progress);
+ *   }
+ * }
+ * ```
+ */
+declare function OnJobProgress(): MethodDecorator;
+/**
+ * Decorator for handling job stalled events
+ *
+ * @example
+ * ```typescript
+ * @Processor('my-queue')
+ * class MyProcessor {
+ *   @OnJobStalled()
+ *   async handleStalled(jobId: string) {
+ *     console.warn(`Job ${jobId} stalled`);
+ *   }
+ * }
+ * ```
+ */
+declare function OnJobStalled(): MethodDecorator;
+/**
+ * Decorator for handling worker ready events
+ */
+declare function OnWorkerReady(): MethodDecorator;
+/**
+ * Decorator for handling worker error events
+ */
+declare function OnWorkerError(): MethodDecorator;
+/**
+ * Get all event handlers from a processor class
+ * @param target - The processor class
+ */
+declare function getEventHandlers(target: Function): EventHandlerMeta[];
+/**
+ * Get event handlers for a specific event
+ * @param target - The processor class
+ * @param event - The event name
+ */
+declare function getEventHandlersFor(target: Function, event: QueueEventName$1): EventHandlerMeta[];
+
+/**
+ * QueueProvider - Main provider for queue lifecycle management
+ *
+ * Implements OnProviderInit and OnProviderDestroy for Rikta lifecycle integration.
+ * Not @Injectable - use createQueueProvider() factory function.
+ */
+
+/**
+ * QueueProvider manages the lifecycle of all queues and workers.
+ *
+ * @example
+ * ```typescript
+ * const provider = createQueueProvider({
+ *   config: { redis: { host: 'localhost', port: 6379 } }
+ * });
+ *
+ * // In Rikta bootstrap:
+ * await app.register(provider);
+ * ```
+ */
+declare class QueueProvider implements OnProviderInit, OnProviderDestroy {
+    private connectionManager;
+    private config;
+    private queues;
+    private workers;
+    private processorClasses;
+    private initialized;
+    private eventBus;
+    private options;
+    /**
+     * Configure the provider with options
+     */
+    configure(options: QueueProviderOptions): this;
+    /**
+     * Register processor classes for auto-discovery
+     */
+    registerProcessors(...processors: Function[]): this;
+    /**
+     * Set EventBus for event emission (optional)
+     */
+    setEventBus(eventBus: unknown): this;
+    /**
+     * Initialize all queues and workers (called by Rikta lifecycle)
+     */
+    onProviderInit(): Promise<void>;
+    /**
+     * Gracefully shutdown all workers and close connections
+     */
+    onProviderDestroy(): Promise<void>;
+    /**
+     * Get a queue by name
+     */
+    getQueue(name: string): Queue$1 | undefined;
+    /**
+     * Get all registered queues
+     */
+    getAllQueues(): Queue$1[];
+    /**
+     * Check if the provider is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Get configuration
+     */
+    getConfig(): QueueConfig;
+    private testConnection;
+    private discoverAndRegisterProcessors;
+    private registerProcessor;
+    private createQueue;
+    private attachWorkerEvents;
+    private handleEvent;
+    /**
+     * Create a processor instance using the DI Container to support @Autowired
+     */
+    private createProcessorInstance;
+    /**
+     * Register QueueProvider and QueueService in the DI container.
+     * Called early so processors can inject QueueService via @Autowired.
+     * Individual queues and workers are registered as they are created.
+     */
+    private registerInContainer;
+    /**
+     * Register a queue and its worker in the DI container.
+     * Called when a queue is created during processor registration.
+     */
+    private registerQueueInContainer;
+    /**
+     * Register a worker in the DI container.
+     * Called when a worker is created during processor registration.
+     */
+    private registerWorkerInContainer;
+    private delay;
+}
+/**
+ * Factory function to create a QueueProvider
+ */
+declare function createQueueProvider(options?: QueueProviderOptions): QueueProvider;
+/**
+ * Error thrown when queue initialization fails
+ */
+declare class QueueInitializationError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Error thrown when a duplicate queue is detected
+ */
+declare class DuplicateQueueError extends Error {
+    constructor(queueName: string);
+}
+
+/**
+ * QueueService - Injectable service for adding jobs to queues
+ */
+
+/**
+ * Service for adding jobs to queues from anywhere in the application.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class NotificationService {
+ *   @Autowired()
+ *   private queueService!: QueueService;
+ *
+ *   async sendNotification(userId: string, message: string) {
+ *     await this.queueService.addJob('notifications', 'send', {
+ *       userId,
+ *       message,
+ *     });
+ *   }
+ * }
+ * ```
+ */
+declare class QueueService {
+    private readonly provider;
+    constructor(provider: QueueProvider);
+    /**
+     * Add a job to a queue
+     *
+     * @param queueName - Name of the queue
+     * @param jobName - Name of the job (matches @Process decorator)
+     * @param data - Job payload data
+     * @param options - Optional job options
+     * @returns The created job
+     */
+    addJob<TData = unknown, TResult = unknown>(queueName: string, jobName: string, data: TData, options?: AddJobOptions): Promise<Job<TData, TResult>>;
+    /**
+     * Add multiple jobs to a queue in bulk
+     *
+     * @param queueName - Name of the queue
+     * @param jobs - Array of jobs to add
+     * @returns Array of created jobs
+     */
+    addJobs<TData = unknown, TResult = unknown>(queueName: string, jobs: Array<{
+        name: string;
+        data: TData;
+        options?: JobsOptions;
+    }>): Promise<Job<TData, TResult>[]>;
+    /**
+     * Add a delayed job
+     *
+     * @param queueName - Name of the queue
+     * @param jobName - Name of the job
+     * @param data - Job payload data
+     * @param delay - Delay in milliseconds
+     * @param options - Optional job options
+     */
+    addDelayedJob<TData = unknown, TResult = unknown>(queueName: string, jobName: string, data: TData, delay: number, options?: JobsOptions): Promise<Job<TData, TResult>>;
+    /**
+     * Add a repeatable job (scheduled)
+     *
+     * @param queueName - Name of the queue
+     * @param jobName - Name of the job
+     * @param data - Job payload data
+     * @param repeat - Repeat options (cron pattern, interval, etc.)
+     * @param options - Optional schedule options
+     */
+    addRepeatableJob<TData = unknown, TResult = unknown>(queueName: string, jobName: string, data: TData, repeat: RepeatOptions, options?: ScheduleOptions): Promise<Job<TData, TResult>>;
+    /**
+     * Remove a repeatable job
+     *
+     * @param queueName - Name of the queue
+     * @param jobName - Name of the job
+     * @param repeat - The repeat options used when creating the job
+     */
+    removeRepeatableJob(queueName: string, jobName: string, repeat: RepeatOptions): Promise<boolean>;
+    /**
+     * Get a job by ID
+     *
+     * @param queueName - Name of the queue
+     * @param jobId - Job ID
+     */
+    getJob<TData = unknown, TResult = unknown>(queueName: string, jobId: string): Promise<Job<TData, TResult> | undefined>;
+    /**
+     * Get queue statistics
+     *
+     * @param queueName - Name of the queue
+     */
+    getQueueStats(queueName: string): Promise<{
+        waiting: number;
+        active: number;
+        completed: number;
+        failed: number;
+        delayed: number;
+        paused: number;
+    }>;
+    /**
+     * Pause a queue
+     */
+    pauseQueue(queueName: string): Promise<void>;
+    /**
+     * Resume a queue
+     */
+    resumeQueue(queueName: string): Promise<void>;
+    /**
+     * Clear all jobs from a queue
+     *
+     * @param queueName - Name of the queue
+     * @param status - Which jobs to clear (default: all)
+     */
+    clearQueue(queueName: string, status?: 'completed' | 'failed' | 'delayed' | 'wait' | 'active'): Promise<void>;
+    /**
+     * Get all queue names
+     */
+    getQueueNames(): string[];
+    private getQueueOrThrow;
+}
+/**
+ * Error thrown when a queue is not found
+ */
+declare class QueueNotFoundError extends Error {
+    constructor(queueName: string);
+}
+/**
+ * Error thrown when job validation fails
+ */
+declare class JobValidationError extends Error {
+    readonly errors: unknown[];
+    constructor(message: string, errors: unknown[]);
+}
+
+/**
+ * Queue events integration with Rikta's EventBus
+ */
+/** Event names for queue events */
+type QueueEventName = 'job:added' | 'job:completed' | 'job:failed' | 'job:progress' | 'job:stalled' | 'job:delayed' | 'job:removed' | 'worker:ready' | 'worker:closed' | 'worker:error';
+/** Event bus event names with prefix */
+declare const QUEUE_EVENTS: {
+    readonly JOB_ADDED: "queue:job:added";
+    readonly JOB_COMPLETED: "queue:job:completed";
+    readonly JOB_FAILED: "queue:job:failed";
+    readonly JOB_PROGRESS: "queue:job:progress";
+    readonly JOB_STALLED: "queue:job:stalled";
+    readonly JOB_DELAYED: "queue:job:delayed";
+    readonly JOB_REMOVED: "queue:job:removed";
+    readonly WORKER_READY: "queue:worker:ready";
+    readonly WORKER_CLOSED: "queue:worker:closed";
+    readonly WORKER_ERROR: "queue:worker:error";
+};
+/**
+ * Map internal event names to EventBus event names
+ */
+declare function getEventBusEventName(event: QueueEventName): string;
+/**
+ * Publish a queue event to the EventBus
+ *
+ * @param eventBus - Rikta's EventBus instance
+ * @param event - The event name
+ * @param queueName - The queue name
+ * @param args - Event arguments (job, result, error, etc.)
+ */
+declare function publishQueueEvent(eventBus: unknown, event: QueueEventName, queueName: string, ...args: unknown[]): Promise<void>;
+
+/**
+ * Bull Board integration for queue monitoring
+ *
+ * This module provides optional Bull Board dashboard integration.
+ * Bull Board packages are NOT included as dependencies - install them separately:
+ *
+ * npm install @bull-board/api @bull-board/fastify
+ *
+ * @example
+ * ```typescript
+ * import { registerBullBoard } from '@riktajs/queue';
+ *
+ * // In your Rikta bootstrap:
+ * const app = await Rikta.create();
+ *
+ * // After queue provider is initialized:
+ * await registerBullBoard(app.server, {
+ *   queues: queueProvider.getAllQueues(),
+ *   path: '/admin/queues',
+ *   auth: async (req) => {
+ *     // Your auth logic here
+ *     return req.headers.authorization === 'Bearer secret';
+ *   },
+ * });
+ * ```
+ */
+
+/** Options for Bull Board registration */
+interface BullBoardOptions {
+    /** Queues to display in the dashboard */
+    queues: Queue$1[];
+    /** Base path for the dashboard (default: '/admin/queues') */
+    path?: string;
+    /** Authentication function - return true to allow access */
+    auth?: (request: FastifyRequest) => boolean | Promise<boolean>;
+    /** Whether to use read-only mode */
+    readOnly?: boolean;
+}
+/** Result of Bull Board registration */
+interface BullBoardResult {
+    /** The path where the dashboard is mounted */
+    path: string;
+    /** Function to add more queues dynamically */
+    addQueue: (queue: Queue$1) => void;
+    /** Function to remove a queue from the dashboard */
+    removeQueue: (queueName: string) => void;
+}
+/**
+ * Register Bull Board dashboard with Fastify
+ *
+ * @param app - Fastify instance
+ * @param options - Dashboard configuration
+ * @returns Bull Board control object
+ *
+ * @throws BullBoardNotInstalledError if @bull-board packages are not installed
+ *
+ * @example
+ * ```typescript
+ * const board = await registerBullBoard(app.server, {
+ *   queues: queueProvider.getAllQueues(),
+ *   path: '/admin/queues',
+ *   auth: (req) => checkAdminAuth(req),
+ * });
+ *
+ * // Add more queues later
+ * board.addQueue(newQueue);
+ * ```
+ */
+declare function registerBullBoard(app: FastifyInstance, options: BullBoardOptions): Promise<BullBoardResult>;
+/**
+ * Error thrown when Bull Board packages are not installed
+ */
+declare class BullBoardNotInstalledError extends Error {
+    constructor();
+}
+
+/**
+ * Redis connection utilities
+ */
+
+/**
+ * Create a Redis client based on configuration
+ * @param config - Redis connection options
+ */
+declare function createRedisClient(config: RedisConnectionOptions): Redis | Cluster;
+/**
+ * Error thrown when Redis connection fails
+ */
+declare class QueueConnectionError extends Error {
+    readonly host?: string | undefined;
+    readonly port?: number | undefined;
+    readonly cause?: Error | undefined;
+    constructor(message: string, host?: string | undefined, port?: number | undefined, cause?: Error | undefined);
+}
+/**
+ * Manages a shared Redis connection for all queues
+ */
+declare class RedisConnectionManager {
+    private client;
+    private config;
+    /**
+     * Initialize the connection manager with configuration
+     */
+    configure(config: RedisConnectionOptions): this;
+    /**
+     * Get or create the Redis client
+     */
+    getClient(): Redis | Cluster;
+    /**
+     * Check if client is connected
+     */
+    isConnected(): boolean;
+    /**
+     * Close the Redis connection
+     */
+    close(): Promise<void>;
+    /**
+     * Disconnect immediately (force)
+     */
+    disconnect(): void;
+}
+
+/**
+ * Zod validation utilities for job payloads
+ */
+
+/**
+ * Creates a wrapper around a Zod schema for job validation
+ *
+ * @param schema - The Zod schema to use for validation
+ * @returns A wrapped schema with job-specific utilities
+ *
+ * @example
+ * ```typescript
+ * const EmailJobSchema = createJobSchema(z.object({
+ *   to: z.string().email(),
+ *   subject: z.string().min(1),
+ *   body: z.string(),
+ * }));
+ *
+ * // Validate job data
+ * const result = EmailJobSchema.validate({ to: 'test@example.com', subject: 'Hello', body: 'World' });
+ * ```
+ */
+declare function createJobSchema<T>(schema: ZodSchema<T>): JobSchema<T>;
+/**
+ * Wrapper class for Zod schemas with job-specific utilities
+ */
+declare class JobSchema<T> {
+    private readonly schema;
+    constructor(schema: ZodSchema<T>);
+    /**
+     * Get the underlying Zod schema
+     */
+    getSchema(): ZodSchema<T>;
+    /**
+     * Validate job data
+     * @throws JobValidationError if validation fails
+     */
+    validate(data: unknown): T;
+    /**
+     * Validate job data, returning undefined on failure
+     */
+    validateSafe(data: unknown): T | undefined;
+    /**
+     * Check if data is valid without throwing
+     */
+    isValid(data: unknown): data is T;
+    /**
+     * Get validation errors for data
+     */
+    getErrors(data: unknown): string[];
+    /**
+     * Parse and transform data with defaults
+     */
+    parse(data: unknown): T;
+}
+/**
+ * Error thrown when job schema validation fails
+ */
+declare class JobSchemaValidationError extends Error {
+    readonly zodError: ZodError;
+    constructor(message: string, zodError: ZodError);
+    /**
+     * Get formatted validation errors
+     */
+    getErrors(): Array<{
+        path: string;
+        message: string;
+    }>;
+}
+
+/**
+ * Common job schemas for typical use cases
+ */
+declare const CommonJobSchemas: {
+    /**
+     * Email job schema
+     */
+    email: z.ZodObject<{
+        to: z.ZodString;
+        cc: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        bcc: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        subject: z.ZodString;
+        body: z.ZodString;
+        html: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            filename: z.ZodString;
+            content: z.ZodString;
+            contentType: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+    /**
+     * Notification job schema
+     */
+    notification: z.ZodObject<{
+        userId: z.ZodString;
+        title: z.ZodString;
+        message: z.ZodString;
+        type: z.ZodDefault<z.ZodEnum<{
+            error: "error";
+            success: "success";
+            info: "info";
+            warning: "warning";
+        }>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+    /**
+     * File processing job schema
+     */
+    fileProcessing: z.ZodObject<{
+        fileId: z.ZodString;
+        filePath: z.ZodString;
+        operation: z.ZodEnum<{
+            resize: "resize";
+            compress: "compress";
+            convert: "convert";
+            thumbnail: "thumbnail";
+        }>;
+        options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+    /**
+     * Webhook job schema
+     */
+    webhook: z.ZodObject<{
+        url: z.ZodString;
+        method: z.ZodDefault<z.ZodEnum<{
+            DELETE: "DELETE";
+            GET: "GET";
+            PATCH: "PATCH";
+            POST: "POST";
+            PUT: "PUT";
+        }>>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        body: z.ZodOptional<z.ZodUnknown>;
+        timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, z.core.$strip>;
+};
+
+export { type AddJobOptions, BullBoardNotInstalledError, type BullBoardOptions, type BullBoardResult, CommonJobSchemas, DuplicateQueueError, type EventHandlerMeta, type JobHandlerMeta, JobSchema, JobSchemaValidationError, JobValidationError, METADATA_KEY, OnJobComplete, OnJobFailed, OnJobProgress, OnJobStalled, OnWorkerError, OnWorkerReady, Process, Processor, ProcessorDecoratorError, type ProcessorOptions, QUEUE_CONFIG, QUEUE_EVENTS, QUEUE_PROVIDER, QUEUE_REDIS_CONNECTION, QUEUE_SERVICE, Queue, type QueueConfig, QueueConfigError, type QueueConfigInput, QueueConfigSchema, QueueConnectionError, QueueDecoratorError, type QueueDecoratorOptions, type QueueEventName, type QueueEventPayload, QueueInitializationError, QueueNotFoundError, QueueProvider, type QueueProviderOptions, QueueService, RedisConnectionManager, type RedisConnectionOptions, type ScheduleOptions, createJobSchema, createQueueProvider, createRedisClient, getEventBusEventName, getEventHandlers, getEventHandlersFor, getJobHandlers, getProcessorOptions, getQueueOptions, getQueueToken, getWorkerToken, isJobHandler, isProcessor, isQueue, loadQueueConfig, publishQueueEvent, registerBullBoard };