@gravito/stream 2.0.1 → 2.0.2

package/dist/index.d.ts

@@ -1,132 +1,639 @@
 import { EventEmitter } from 'node:events';
-import { GravitoOrbit, PlanetCore } from '@gravito/core';
+import { GravitoOrbit, PlanetCore, EventBackend, EventTask } from '@gravito/core';
 import { ConnectionContract } from '@gravito/atlas';
 
+/**
+ * Defines the contract for queueable items (jobs) with fluent configuration.
+ *
+ * This interface enables method chaining for configuring job properties such as
+ * target queue, connection, delay, and priority before dispatching. It ensures
+ * consistent API surface across different job implementations.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * class MyJob implements Queueable {
+ *   queueName?: string
+ *   // ... implementation
+ *   onQueue(queue: string): this {
+ *     this.queueName = queue
+ *     return this
+ *   }
+ *   // ...
+ * }
+ * ```
+ */
+interface Queueable {
+    /**
+     * The specific queue name where the job should be processed.
+     *
+     * If not set, the default queue for the connection will be used.
+     */
+    queueName?: string;
+    /**
+     * The connection name (e.g., 'redis', 'sqs') to use for this job.
+     *
+     * If not set, the default connection configured in QueueManager will be used.
+     */
+    connectionName?: string;
+    /**
+     * The number of seconds to delay the job execution.
+     */
+    delaySeconds?: number;
+    /**
+     * The priority level of the job.
+     */
+    priority?: string | number;
+    /**
+     * Sets the target queue for the job.
+     *
+     * @param queue - The name of the queue to push the job to.
+     * @returns The instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * job.onQueue('notifications');
+     * ```
+     */
+    onQueue(queue: string): this;
+    /**
+     * Sets the target connection for the job.
+     *
+     * @param connection - The name of the connection to use.
+     * @returns The instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * job.onConnection('sqs');
+     * ```
+     */
+    onConnection(connection: string): this;
+    /**
+     * Sets the priority of the job.
+     *
+     * @param priority - The priority level (e.g., 'high', 'low', 10).
+     * @returns The instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * job.withPriority('critical');
+     * ```
+     */
+    withPriority(priority: string | number): this;
+    /**
+     * Sets a delay before the job is available for processing.
+     *
+     * @param delay - The delay in seconds.
+     * @returns The instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * job.delay(300); // 5 minutes
+     * ```
+     */
+    delay(delay: number): this;
+}
+
+/**
+ * Abstract base class for all background jobs.
+ *
+ * This class serves as the foundation for creating queueable tasks. It implements the `Queueable`
+ * interface for fluent configuration and provides the core structure for defining execution logic (`handle`)
+ * and failure handling (`failed`).
+ *
+ * Subclasses must implement the `handle` method.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * export class SendEmailJob extends Job {
+ *   constructor(private email: string, private subject: string) {
+ *     super();
+ *   }
+ *
+ *   async handle(): Promise<void> {
+ *     await emailService.send(this.email, this.subject);
+ *   }
+ * }
+ *
+ * // Usage
+ * await queue.push(new SendEmailJob('user@example.com', 'Welcome'))
+ *   .onQueue('emails')
+ *   .delay(60);
+ * ```
+ */
+declare abstract class Job implements Queueable {
+    /**
+     * Unique identifier for the job instance.
+     *
+     * Assigned automatically when the job is pushed to the queue.
+     */
+    id?: string;
+    /**
+     * The name of the queue where this job will be processed.
+     */
+    queueName?: string;
+    /**
+     * The name of the connection used to transport this job.
+     */
+    connectionName?: string;
+    /**
+     * Delay in seconds before the job becomes available for processing.
+     */
+    delaySeconds?: number;
+    /**
+     * The current attempt number (starts at 1).
+     */
+    attempts?: number;
+    /**
+     * The maximum number of retry attempts allowed.
+     *
+     * Can be overridden by the worker configuration or per-job using `maxAttempts`.
+     */
+    maxAttempts?: number;
+    /**
+     * Group ID for sequential processing.
+     *
+     * Jobs with the same `groupId` will be processed in strict order (FIFO)
+     * if the consumer supports it.
+     */
+    groupId?: string;
+    /**
+     * Priority level of the job.
+     */
+    priority?: string | number;
+    /**
+     * Initial delay in seconds before the first retry attempt.
+     *
+     * Used for exponential backoff calculation.
+     */
+    retryAfterSeconds?: number;
+    /**
+     * Multiplier applied to the retry delay for each subsequent attempt.
+     *
+     * Used for exponential backoff calculation.
+     */
+    retryMultiplier?: number;
+    /**
+     * Sets the target queue for the job.
+     *
+     * @param queue - The name of the target queue.
+     * @returns The job instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * job.onQueue('billing');
+     * ```
+     */
+    onQueue(queue: string): this;
+    /**
+     * Sets the target connection for the job.
+     *
+     * @param connection - The name of the connection (e.g., 'redis').
+     * @returns The job instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * job.onConnection('sqs-primary');
+     * ```
+     */
+    onConnection(connection: string): this;
+    /**
+     * Sets the priority of the job.
+     *
+     * @param priority - The priority level (e.g., 'high', 10).
+     * @returns The job instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * job.withPriority('high');
+     * ```
+     */
+    withPriority(priority: string | number): this;
+    /**
+     * Delays the job execution.
+     *
+     * @param delay - Delay in seconds.
+     * @returns The job instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * job.delay(60); // Run after 1 minute
+     * ```
+     */
+    delay(delay: number): this;
+    /**
+     * Configures the exponential backoff strategy for retries.
+     *
+     * @param seconds - Initial delay in seconds before the first retry.
+     * @param multiplier - Factor by which the delay increases for each subsequent attempt (default: 2).
+     * @returns The job instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * // Wait 5s, then 10s, then 20s...
+     * job.backoff(5, 2);
+     * ```
+     */
+    backoff(seconds: number, multiplier?: number): this;
+    /**
+     * Calculates the delay for the next retry attempt based on the backoff strategy.
+     *
+     * Uses the formula: `initialDelay * multiplier^(attempt - 1)`, capped at 1 hour.
+     *
+     * @param attempt - The current attempt number (1-based).
+     * @returns The calculated delay in milliseconds.
+     *
+     * @example
+     * ```typescript
+     * const nextDelay = job.getRetryDelay(2);
+     * ```
+     */
+    getRetryDelay(attempt: number): number;
+    /**
+     * Contains the main business logic of the job.
+     *
+     * This method is called by the worker to process the job.
+     * Implementations should be idempotent if possible.
+     *
+     * @throws {Error} If the job fails and should be retried.
+     */
+    abstract handle(): Promise<void>;
+    /**
+     * Optional handler for when the job has permanently failed.
+     *
+     * Called when the job has exhausted all retry attempts.
+     * Useful for cleaning up resources, sending alerts, or logging.
+     *
+     * @param _error - The error that caused the final failure.
+     *
+     * @example
+     * ```typescript
+     * async failed(error: Error) {
+     *   await notifyAdmin(`Job failed: ${error.message}`);
+     * }
+     * ```
+     */
+    failed(_error: Error): Promise<void>;
+}
+
 /**
  * Represents a job that has been serialized for storage in a queue.
+ *
+ * This interface defines the data structure used to persist jobs in the underlying
+ * storage mechanism (e.g., Redis, Database, SQS). It encapsulates all metadata
+ * required for processing, retries, and lifecycle management.
+ *
  * @public
+ * @example
+ * ```typescript
+ * const job: SerializedJob = {
+ *   id: 'job-123',
+ *   type: 'json',
+ *   data: '{"userId": 1}',
+ *   createdAt: Date.now()
+ * };
+ * ```
  */
 interface SerializedJob {
-    /** Unique job identifier */
+    /**
+     * Unique identifier for the job.
+     */
     id: string;
-    /** Serializer type: 'json' for plain objects or 'class' for instances */
+    /**
+     * The serialization format used for the job data.
+     *
+     * - 'json': Simple JSON objects.
+     * - 'class': Serialized class instances (requires class registration).
+     * - 'msgpack': Binary MessagePack format.
+     */
     type: 'json' | 'class' | 'msgpack';
-    /** Serialized data string */
+    /**
+     * The actual serialized job payload.
+     *
+     * Contains the business data needed to execute the job.
+     */
     data: string;
-    /** Fully qualified class name (only used for 'class' type) */
+    /**
+     * The fully qualified class name of the job.
+     *
+     * Only required when `type` is 'class' to reconstruct the original object instance.
+     */
     className?: string;
-    /** Timestamp when the job was created */
+    /**
+     * The timestamp (in milliseconds) when the job was originally created.
+     */
     createdAt: number;
-    /** Optional delay in seconds before the job becomes available for processing */
+    /**
+     * Optional delay in seconds before the job becomes eligible for processing.
+     *
+     * Used for scheduling future tasks.
+     */
     delaySeconds?: number;
-    /** Number of times the job has been attempted */
+    /**
+     * The number of times this job has been attempted so far.
+     */
     attempts?: number;
-    /** Maximum number of retry attempts before the job is marked as failed */
+    /**
+     * The maximum number of retry attempts allowed before marking the job as failed.
+     */
     maxAttempts?: number;
-    /** Group ID for FIFO (strictly sequential) processing */
+    /**
+     * Group ID for sequential processing.
+     *
+     * Jobs sharing the same `groupId` are guaranteed to be processed in order (FIFO),
+     * provided the consumer supports this feature.
+     */
     groupId?: string;
-    /** Initial delay in seconds before first retry attempt */
+    /**
+     * The initial delay in seconds before the first retry attempt after a failure.
+     */
     retryAfterSeconds?: number;
-    /** Multiplier for exponential backoff on retries */
+    /**
+     * The multiplier applied to the delay for exponential backoff strategies.
+     */
     retryMultiplier?: number;
-    /** Last error message if the job failed */
+    /**
+     * The error message from the last failed attempt, if any.
+     */
     error?: string;
-    /** Timestamp when the job finally failed after max attempts */
+    /**
+     * The timestamp (in milliseconds) when the job was permanently marked as failed.
+     */
     failedAt?: number;
-    /** Optional priority for the job (string or numeric) */
+    /**
+     * The priority level of the job.
+     *
+     * Higher values or specific strings (e.g., 'high') indicate higher priority.
+     */
     priority?: string | number;
 }
 /**
- * Statistics for a single queue.
+ * Statistics snapshot for a specific queue.
+ *
+ * Provides insight into the current state of a queue, including pending,
+ * delayed, reserved, and failed job counts.
+ *
  * @public
+ * @example
+ * ```typescript
+ * const stats: QueueStats = {
+ *   queue: 'default',
+ *   size: 42,
+ *   delayed: 5,
+ *   failed: 1
+ * };
+ * ```
  */
 interface QueueStats {
-    /** Queue name */
+    /** Name of the queue */
     queue: string;
-    /** Number of pending jobs */
+    /** Number of pending jobs waiting to be processed */
     size: number;
-    /** Number of delayed jobs (if supported) */
+    /** Number of jobs scheduled for future execution */
     delayed?: number;
-    /** Number of reserved/in-flight jobs (if supported) */
+    /** Number of jobs currently being processed by workers */
     reserved?: number;
-    /** Number of failed jobs in DLQ (if supported) */
+    /** Number of jobs in the Dead Letter Queue (DLQ) */
     failed?: number;
-    /** Additional custom metrics */
+    /** Driver-specific custom metrics */
     metrics?: Record<string, number>;
 }
 /**
- * Advanced topic options for distributed queues (e.g., Kafka).
+ * Snapshot of statistics across all connections and queues.
+ *
+ * Used by monitoring dashboards to provide a high-level overview
+ * of the entire background processing system.
+ *
+ * @public
+ */
+interface GlobalStats {
+    /** Map of connection names to their respective queue statistics */
+    connections: Record<string, QueueStats[]>;
+    /** Total number of pending jobs across all connections */
+    totalSize: number;
+    /** Total number of failed jobs across all connections */
+    totalFailed: number;
+    /** Timestamp of the snapshot */
+    timestamp: number;
+}
+/**
+ * Advanced topic configuration options for distributed queue systems.
+ *
+ * Used primarily by drivers like Kafka to configure topic properties.
+ *
  * @public
+ * @example
+ * ```typescript
+ * const options: TopicOptions = {
+ *   partitions: 3,
+ *   replicationFactor: 2
+ * };
+ * ```
  */
 interface TopicOptions {
     /** Number of partitions for the topic */
     partitions?: number;
-    /** Number of replicas for each partition */
+    /** Replication factor for fault tolerance */
     replicationFactor?: number;
-    /** Additional driver-specific configurations */
+    /** Additional driver-specific configuration key-values */
     config?: Record<string, string>;
 }
 /**
- * Database driver configuration.
+ * Configuration for the Database driver.
+ *
+ * Configures the queue system to use a SQL database for job storage.
+ *
  * @public
+ * @example
+ * ```typescript
+ * const config: DatabaseDriverConfig = {
+ *   driver: 'database',
+ *   dbService: myDbService,
+ *   table: 'my_jobs'
+ * };
+ * ```
  */
 interface DatabaseDriverConfig$1 {
+    /** Driver type identifier */
     driver: 'database';
     /** Database service implementation for executing queries */
     dbService: any;
-    /** Optional table name for job storage */
+    /** Optional custom table name for storing jobs */
     table?: string;
 }
 /**
- * Redis driver configuration.
+ * Configuration for the Redis driver.
+ *
+ * Configures the queue system to use Redis for high-performance job storage.
+ *
  * @public
+ * @example
+ * ```typescript
+ * const config: RedisDriverConfig = {
+ *   driver: 'redis',
+ *   client: redisClient,
+ *   prefix: 'my-app:queue:'
+ * };
+ * ```
  */
 interface RedisDriverConfig$1 {
+    /** Driver type identifier */
     driver: 'redis';
     /** Redis client instance (ioredis or node-redis compatible) */
     client: any;
-    /** Optional prefix for all Redis keys */
+    /** Optional key prefix for namespacing */
     prefix?: string;
 }
 /**
- * Kafka driver configuration.
+ * Configuration for the Kafka driver.
+ *
+ * Configures the queue system to use Apache Kafka.
+ *
+ * @example
+ * ```typescript
+ * const config: KafkaDriverConfig = {
+ *   driver: 'kafka',
+ *   client: kafkaClient,
+ *   consumerGroupId: 'my-group'
+ * };
+ * ```
  */
 interface KafkaDriverConfig$1 {
+    /** Driver type identifier */
     driver: 'kafka';
+    /** Kafka client instance */
     client: any;
+    /** Consumer group ID for coordinating workers */
     consumerGroupId?: string;
 }
 /**
- * SQS driver configuration.
+ * Configuration for the SQS driver.
+ *
+ * Configures the queue system to use Amazon Simple Queue Service.
+ *
  * @public
+ * @example
+ * ```typescript
+ * const config: SQSDriverConfig = {
+ *   driver: 'sqs',
+ *   client: sqsClient,
+ *   queueUrlPrefix: 'https://sqs.us-east-1.amazonaws.com/123/'
+ * };
+ * ```
  */
 interface SQSDriverConfig$1 {
+    /** Driver type identifier */
     driver: 'sqs';
     /** Amazon SQS client instance */
     client: any;
-    /** Optional prefix for queue URLs */
+    /** Optional prefix for resolving queue names to URLs */
     queueUrlPrefix?: string;
-    /** The duration (in seconds) that the received messages are hidden from subsequent retrieve requests after being retrieved by a ReceiveMessage request. */
+    /** The duration (in seconds) that received messages are hidden from other consumers */
     visibilityTimeout?: number;
-    /** The duration (in seconds) for which the call waits for a message to arrive in the queue before returning. */
+    /** The duration (in seconds) to wait for a message (Long Polling) */
     waitTimeSeconds?: number;
 }
 /**
- * RabbitMQ driver configuration.
+ * Configuration for the RabbitMQ driver.
+ *
+ * Configures the queue system to use RabbitMQ (AMQP).
+ *
+ * @example
+ * ```typescript
+ * const config: RabbitMQDriverConfig = {
+ *   driver: 'rabbitmq',
+ *   client: amqpConnection,
+ *   exchange: 'jobs',
+ *   exchangeType: 'direct'
+ * };
+ * ```
  */
 interface RabbitMQDriverConfig$1 {
+    /** Driver type identifier */
     driver: 'rabbitmq';
+    /** AMQP client instance */
     client: any;
+    /** Exchange name to publish to */
     exchange?: string;
+    /** Type of exchange (direct, topic, fanout, headers) */
     exchangeType?: string;
 }
 /**
- * Configuration for a specific queue connection.
+ * Configuration for the gRPC driver.
+ *
+ * Configures the queue system to use a remote gRPC service.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const config: GrpcDriverConfig = {
+ *   driver: 'grpc',
+ *   url: 'localhost:50051',
+ *   protoUser: 'myuser',
+ *   protoPassword: 'mypassword',
+ *   serviceName: 'QueueService',
+ *   packageName: 'stream'
+ * };
+ * ```
+ */
+interface GrpcDriverConfig {
+    /** Driver type identifier */
+    driver: 'grpc';
+    /** The gRPC server URL (host:port) */
+    url: string;
+    /** Path to the .proto file (optional, defaults to built-in) */
+    protoPath?: string;
+    /** The package name defined in the .proto file (default: 'stream') */
+    packageName?: string;
+    /** The service name defined in the .proto file (default: 'QueueService') */
+    serviceName?: string;
+    /** Optional credentials/metadata for connection */
+    credentials?: {
+        rootCerts?: Buffer;
+        privateKey?: Buffer;
+        certChain?: Buffer;
+    };
+}
+/**
+ * Configuration for the Bull Queue driver.
+ *
+ * Configures the queue system to use Bull Queue (backed by Redis).
+ *
+ * @public
+ * @example
+ * ```typescript
+ * import { Queue } from 'bullmq'
+ * import Redis from 'ioredis'
+ *
+ * const redis = new Redis()
+ * const queue = new Queue('gravito-events', { connection: redis })
+ * const config: BullMQDriverConfig = {
+ *   driver: 'bullmq',
+ *   queue: queue
+ * };
+ * ```
+ */
+interface BullMQDriverConfig$1 {
+    /** Driver type identifier */
+    driver: 'bullmq';
+    /** Bull Queue instance */
+    queue: any;
+    /** Optional Bull Worker instance */
+    worker?: any;
+    /** Key prefix for queue namespacing */
+    prefix?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Union type for all supported queue connection configurations.
+ *
  * @public
  */
 type QueueConnectionConfig = {
     driver: 'memory';
-} | DatabaseDriverConfig$1 | RedisDriverConfig$1 | KafkaDriverConfig$1 | SQSDriverConfig$1 | RabbitMQDriverConfig$1 | {
+} | DatabaseDriverConfig$1 | RedisDriverConfig$1 | KafkaDriverConfig$1 | SQSDriverConfig$1 | RabbitMQDriverConfig$1 | GrpcDriverConfig | BullMQDriverConfig$1 | {
     driver: 'nats';
     [key: string]: unknown;
 } | {
@@ -134,91 +641,137 @@ type QueueConnectionConfig = {
     [key: string]: unknown;
 };
 /**
- * Queue manager config.
+ * Global configuration for the QueueManager.
+ *
+ * Defines available connections, serialization settings, and system-wide behaviors.
+ *
+ * @example
+ * ```typescript
+ * const config: QueueConfig = {
+ *   default: 'redis',
+ *   connections: {
+ *     redis: { driver: 'redis', client: redis }
+ *   },
+ *   debug: true
+ * };
+ * ```
  */
 interface QueueConfig {
     /**
-     * Default connection name.
+     * The name of the default connection to use when none is specified.
      */
     default?: string;
     /**
-     * Connection configs.
+     * Map of connection names to their configurations.
      */
     connections?: Record<string, QueueConnectionConfig>;
     /**
-     * Default serializer type.
+     * The default serialization format to use for jobs.
      */
     defaultSerializer?: 'json' | 'class' | 'msgpack';
     /**
-     * Whether to enable serialization caching.
-     * If true, re-queuing the same Job instance will use the cached serialized data.
+     * Whether to cache serialized job data.
+     *
+     * If true, re-queuing the same Job instance will reuse the cached serialized string,
+     * improving performance for frequently pushed jobs.
+     *
      * @default false
      */
     useSerializationCache?: boolean;
     /**
-     * Enable verbose debug logging for QueueManager and Consumer.
+     * Enable verbose debug logging.
+     *
+     * Useful for troubleshooting queue operations and consumer behavior.
+     *
      * @default false
      */
     debug?: boolean;
     /**
-     * Persistence configuration (SQL Archive).
+     * Configuration for the persistence layer (SQL Archive).
      */
     persistence?: {
         /**
-         * Persistence adapter instance or config.
+         * The persistence adapter instance used to store archived jobs.
          */
         adapter: PersistenceAdapter;
         /**
-         * Whether to automatically archive completed jobs.
+         * Whether to automatically archive jobs upon successful completion.
          */
         archiveCompleted?: boolean;
         /**
-         * Whether to automatically archive failed jobs.
+         * Whether to automatically archive jobs upon permanent failure.
          */
         archiveFailed?: boolean;
         /**
-         * Whether to archive jobs immediately upon enqueue (Audit Mode).
+         * Whether to archive jobs immediately when they are enqueued (Audit Mode).
+         *
          * @default false
          */
         archiveEnqueued?: boolean;
         /**
-         * Buffer size for batched writes.
-         * If set, wraps the adapter in BufferedPersistence.
+         * Buffer size for batched writes to the archive.
+         *
+         * If set, wraps the adapter in a `BufferedPersistence` decorator to improve throughput.
          */
         bufferSize?: number;
         /**
-         * Flush interval in ms for batched writes.
-         * If set, wraps the adapter in BufferedPersistence.
+         * Maximum time (in milliseconds) to wait before flushing the write buffer.
          */
         flushInterval?: number;
     };
 }
 /**
- * Persistence Adapter Interface
- * Used for long-term archiving of jobs in a SQL database.
+ * Interface for persistence adapters.
+ *
+ * Defines the contract for storing long-term history of jobs in a permanent storage
+ * (typically a SQL database).
+ *
+ * @example
+ * ```typescript
+ * class MyPersistence implements PersistenceAdapter {
+ *   async archive(queue, job, status) { ... }
+ *   // ...
+ * }
+ * ```
  */
 interface PersistenceAdapter {
     /**
-     * Archive a job.
+     * Archive a single job.
+     *
+     * @param queue - The name of the queue.
+     * @param job - The serialized job data.
+     * @param status - The final status of the job ('completed', 'failed', etc.).
+     * @returns A promise that resolves when the job is archived.
      */
     archive(queue: string, job: SerializedJob, status: 'completed' | 'failed' | 'waiting' | string): Promise<void>;
     /**
-     * Find a job in the archive.
+     * Find a specific job in the archive.
+     *
+     * @param queue - The name of the queue.
+     * @param id - The job ID.
+     * @returns The serialized job if found, or null.
      */
     find(queue: string, id: string): Promise<SerializedJob | null>;
     /**
-     * List jobs from the archive.
+     * List jobs from the archive based on criteria.
+     *
+     * @param queue - The name of the queue.
+     * @param options - Filtering and pagination options.
+     * @returns A list of matching serialized jobs.
      */
     list(queue: string, options?: {
         limit?: number;
         offset?: number;
-        status?: 'completed' | 'failed' | 'waiting' | string;
+        status?: 'completed' | 'failed' | 'waiting' | string | string[];
         jobId?: string;
         startTime?: Date;
         endTime?: Date;
     }): Promise<SerializedJob[]>;
     /**
-     * Archive multiple jobs (batch write).
+     * Archive multiple jobs in a single batch operation.
+     *
+     * @param jobs - Array of job data to archive.
+     * @returns A promise that resolves when all jobs are archived.
      */
     archiveMany?(jobs: Array<{
         queue: string;
@@ -227,23 +780,35 @@ interface PersistenceAdapter {
     }>): Promise<void>;
     /**
      * Remove old data from the archive.
+     *
+     * @param days - Retention period in days; older records will be deleted.
+     * @returns The number of records deleted.
      */
     cleanup(days: number): Promise<number>;
     /**
-     * Flush any buffered data.
+     * Flush any buffered data to storage.
+     *
+     * @returns A promise that resolves when the flush is complete.
      */
     flush?(): Promise<void>;
     /**
-     * Count jobs in the archive.
+     * Count jobs in the archive matching specific criteria.
+     *
+     * @param queue - The name of the queue.
+     * @param options - Filtering options.
+     * @returns The total count of matching jobs.
      */
     count(queue: string, options?: {
-        status?: 'completed' | 'failed' | 'waiting' | string;
+        status?: 'completed' | 'failed' | 'waiting' | string | string[];
         jobId?: string;
         startTime?: Date;
         endTime?: Date;
     }): Promise<number>;
     /**
      * Archive a system log message.
+     *
+     * @param log - The log entry to archive.
+     * @returns A promise that resolves when the log is archived.
      */
     archiveLog(log: {
         level: string;
@@ -253,7 +818,10 @@ interface PersistenceAdapter {
         timestamp: Date;
     }): Promise<void>;
     /**
-     * Archive multiple log messages (batch write).
+     * Archive multiple log messages in a batch.
+     *
+     * @param logs - Array of log entries to archive.
+     * @returns A promise that resolves when logs are archived.
      */
     archiveLogMany?(logs: Array<{
         level: string;
@@ -264,6 +832,9 @@ interface PersistenceAdapter {
     }>): Promise<void>;
     /**
      * List system logs from the archive.
+     *
+     * @param options - Filtering and pagination options.
+     * @returns A list of matching log entries.
      */
     listLogs(options?: {
         limit?: number;
@@ -277,6 +848,9 @@ interface PersistenceAdapter {
     }): Promise<any[]>;
     /**
      * Count system logs in the archive.
+     *
+     * @param options - Filtering options.
+     * @returns The total count of matching logs.
      */
     countLogs(options?: {
         level?: string;
@@ -288,18 +862,31 @@ interface PersistenceAdapter {
     }): Promise<number>;
 }
 /**
- * Options when pushing a job.
+ * Options used when pushing a job to the queue.
+ *
+ * Allows customizing delivery behavior, such as delays, priority, and ordering.
+ *
+ * @example
+ * ```typescript
+ * const options: JobPushOptions = {
+ *   priority: 'high',
+ *   groupId: 'user-123'
+ * };
+ * ```
  */
 interface JobPushOptions {
     /**
-     * Group ID for FIFO ordering (e.g. userId).
-     * If set, jobs with the same groupId will be processed strictly sequentially.
+     * Group ID for FIFO ordering.
+     *
+     * If provided, jobs with the same `groupId` are guaranteed to be processed strictly
+     * sequentially. This is useful for event streams where order matters (e.g., per-user events).
      */
     groupId?: string;
     /**
-     * Job priority.
-     * Higher priority jobs are processed first (if supported by driver).
-     * Example: 'high', 'low', 'critical'
+     * Job priority level.
+     *
+     * Higher priority jobs are processed before lower priority ones, depending on driver support.
+     * Common values: 'critical', 'high', 'default', 'low'.
      */
     priority?: string | number;
 }
@@ -307,122 +894,143 @@ interface JobPushOptions {
 /**
  * Queue driver interface.
  *
- * All queue drivers must implement this interface.
- * Defines basic queue operations plus optional enterprise-grade capabilities.
+ * Defines the contract that all storage backends (Redis, Database, SQS, etc.) must implement
+ * to be compatible with the QueueManager. It covers the basic operations for a job queue:
+ * push, pop, size, and clear.
  *
+ * Advanced capabilities like rate limiting, reliable delivery (acknowledgements), and
+ * batch operations are optional but recommended for high-performance drivers.
+ *
+ * @public
  * @example
  * ```typescript
- * class MyDriver implements QueueDriver {
- *   async push(queue: string, job: SerializedJob, options?: JobPushOptions): Promise<void> {
- *     // push a job
- *   }
- *
- *   async pop(queue: string): Promise<SerializedJob | null> {
- *     // pop a job
- *   }
- *
- *   async complete(queue: string, job: SerializedJob): Promise<void> {
- *     // job completed (for FIFO handling)
- *   }
- *
- *   async size(queue: string): Promise<number> {
- *     // queue size
+ * class MyCustomDriver implements QueueDriver {
+ *   async push(queue: string, job: SerializedJob) {
+ *     // ... write to storage
  *   }
- *
- *   async clear(queue: string): Promise<void> {
- *     // clear queue
+ *   async pop(queue: string) {
+ *     // ... read from storage
+ *     return job;
  *   }
+ *   async size(queue: string) { return 0; }
+ *   async clear(queue: string) {}
  * }
  * ```
  */
 interface QueueDriver {
     /**
-     * Push a job to a queue.
-     * @param queue - Queue name
-     * @param job - Serialized job
-     * @param options - Push options (e.g. groupId)
+     * Pushes a job onto the specified queue.
+     *
+     * @param queue - The name of the queue.
+     * @param job - The serialized job data.
+     * @param options - Optional parameters like priority or group ID.
+     * @returns A promise that resolves when the job is successfully stored.
      */
     push(queue: string, job: SerializedJob, options?: JobPushOptions): Promise<void>;
     /**
-     * Pop a job from a queue (non-blocking).
-     * @param queue - Queue name
-     * @returns Serialized job, or `null` if the queue is empty
+     * Retrieves and removes the next job from the queue (FIFO).
+     *
+     * @param queue - The name of the queue.
+     * @returns The serialized job if available, or `null` if the queue is empty.
      */
     pop(queue: string): Promise<SerializedJob | null>;
     /**
-     * Pop a job from a queue (blocking).
-     * @param queues - Queue name or array of queue names
-     * @param timeout - Timeout in seconds
-     * @returns Serialized job, or `null` if timeout reached
+     * Blocking version of `pop`. Waits for a job to arrive if the queue is empty.
+     *
+     * @param queues - A single queue name or an array of queues to listen to.
+     * @param timeout - The maximum time to wait in seconds (0 means indefinite).
+     * @returns The serialized job if one arrives within the timeout, or `null`.
      */
     popBlocking?(queues: string | string[], timeout: number): Promise<SerializedJob | null>;
     /**
-     * Mark a job as completed (used for FIFO/Group handling).
-     * @param queue - Queue name
-     * @param job - Serialized job
+     * Marks a job as completed.
+     *
+     * Used primarily by drivers that support advanced flow control (like FIFO groups)
+     * or explicit acknowledgement (like SQS/RabbitMQ).
+     *
+     * @param queue - The name of the queue.
+     * @param job - The job that was completed.
      */
     complete?(queue: string, job: SerializedJob): Promise<void>;
     /**
-     * Get queue size.
-     * @param queue - Queue name
-     * @returns Number of jobs in the queue
+     * Returns the number of jobs currently waiting in the queue.
+     *
+     * @param queue - The name of the queue.
+     * @returns The count of pending jobs.
      */
     size(queue: string): Promise<number>;
     /**
-     * Clear a queue.
-     * @param queue - Queue name
+     * Removes all jobs from the specified queue.
+     *
+     * @param queue - The name of the queue to purge.
      */
     clear(queue: string): Promise<void>;
     /**
-     * Mark a job as permanently failed (move to DLQ).
-     * @param queue - Queue name
-     * @param job - Serialized job with error info
+     * Moves a job to the Dead Letter Queue (DLQ) after repeated failures.
+     *
+     * @param queue - The original queue name.
+     * @param job - The job data (usually including error information).
      */
     fail?(queue: string, job: SerializedJob): Promise<void>;
     /**
-     * Get queue statistics including pending, delayed, and failed job counts.
-     * @param queue - Queue name
+     * Retrieves detailed statistics for a queue.
+     *
+     * @param queue - The name of the queue.
+     * @returns An object containing counts for pending, delayed, failed, etc.
      */
     stats?(queue: string): Promise<QueueStats>;
     /**
-     * Push multiple jobs (optional, higher throughput).
-     * @param queue - Queue name
-     * @param jobs - Serialized job array
+     * Pushes multiple jobs to the queue in a single batch operation.
+     *
+     * @param queue - The name of the queue.
+     * @param jobs - An array of serialized jobs.
      */
     pushMany?(queue: string, jobs: SerializedJob[]): Promise<void>;
     /**
-     * Pop multiple jobs (optional, higher throughput).
-     * @param queue - Queue name
-     * @param count - Max number of jobs to pop
-     * @returns Serialized job array
+     * Retrieves multiple jobs from the queue in a single batch operation.
+     *
+     * @param queue - The name of the queue.
+     * @param count - The maximum number of jobs to retrieve.
+     * @returns An array of serialized jobs.
      */
     popMany?(queue: string, count: number): Promise<SerializedJob[]>;
     /**
-     * Acknowledge a message (enterprise capability, e.g. Kafka/SQS).
-     * @param messageId - Message ID
+     * Acknowledges a specific message by its ID.
+     *
+     * Used for drivers that require explicit acknowledgement (e.g., SQS, Kafka).
+     *
+     * @param messageId - The ID of the message to acknowledge.
      */
     acknowledge?(messageId: string): Promise<void>;
     /**
-     * Subscribe to a queue (push-based model, e.g. Kafka/SQS).
-     * @param queue - Queue name
-     * @param callback - Callback to process jobs
+     * Subscribes to a queue for real-time job processing (Push model).
+     *
+     * Alternative to polling (`pop`). The driver pushes jobs to the callback as they arrive.
+     *
+     * @param queue - The name of the queue.
+     * @param callback - The function to call when a job is received.
      */
     subscribe?(queue: string, callback: (job: SerializedJob) => Promise<void>): Promise<void>;
     /**
-     * Create a topic (Kafka, etc.).
-     * @param topic - Topic name
-     * @param options - Topic options
+     * Creates a new topic or queue (for drivers like Kafka/RabbitMQ).
+     *
+     * @param topic - The name of the topic/queue.
+     * @param options - Configuration options (partitions, replication, etc.).
      */
     createTopic?(topic: string, options?: TopicOptions): Promise<void>;
     /**
-     * Delete a topic (Kafka, etc.).
-     * @param topic - Topic name
+     * Deletes a topic or queue.
+     *
+     * @param topic - The name of the topic/queue to delete.
      */
     deleteTopic?(topic: string): Promise<void>;
     /**
-     * Report worker heartbeat for monitoring.
-     * @param workerInfo - Worker information
-     * @param prefix - Optional prefix for monitoring keys
+     * Sends a heartbeat signal for a worker instance.
+     *
+     * Used for monitoring worker health and presence.
+     *
+     * @param workerInfo - Metadata about the worker (ID, status, resources).
+     * @param prefix - Optional key prefix for storage.
      */
     reportHeartbeat?(workerInfo: {
         id: string;
@@ -436,9 +1044,10 @@ interface QueueDriver {
         [key: string]: any;
     }, prefix?: string): Promise<void>;
     /**
-     * Publish a log message for monitoring.
-     * @param logPayload - Log payload
-     * @param prefix - Optional prefix for monitoring channels/keys
+     * Publishes a log entry to the monitoring system.
+     *
+     * @param logPayload - The log data (level, message, context).
+     * @param prefix - Optional key prefix.
      */
     publishLog?(logPayload: {
         level: string;
@@ -449,291 +1058,260 @@ interface QueueDriver {
         [key: string]: any;
     }, prefix?: string): Promise<void>;
     /**
-     * Check if a queue is rate limited.
-     * @param queue - Queue name
-     * @param config - Rate limit configuration
-     * @returns true if allowed, false if limited
+     * Checks if a specific queue has exceeded its rate limit.
+     *
+     * @param queue - The name of the queue.
+     * @param config - The rate limit rules (max jobs per duration).
+     * @returns `true` if the job is allowed to proceed, `false` if limited.
      */
     checkRateLimit?(queue: string, config: {
         max: number;
         duration: number;
     }): Promise<boolean>;
     /**
-     * Retry failed jobs from DLQ.
-     * @param queue - Queue name
-     * @param count - Optional count (default: all)
-     * @returns Number of jobs retried
+     * Retries failed jobs from the Dead Letter Queue.
+     *
+     * Moves jobs from the DLQ back to the active queue.
+     *
+     * @param queue - The name of the queue.
+     * @param count - The number of jobs to retry (optional).
+     * @returns The number of jobs actually moved.
      */
     retryFailed?(queue: string, count?: number): Promise<number>;
     /**
-     * Get failed jobs from DLQ.
-     * @param queue - Queue name
-     * @param start - Start index
-     * @param end - End index
-     * @returns Array of failed jobs
+     * Retrieves a list of failed jobs from the Dead Letter Queue.
+     *
+     * @param queue - The name of the queue.
+     * @param start - Pagination start index.
+     * @param end - Pagination end index.
+     * @returns An array of failed jobs.
      */
     getFailed?(queue: string, start?: number, end?: number): Promise<SerializedJob[]>;
     /**
-     * Clear failed jobs from DLQ.
-     * @param queue - Queue name
+     * Clears the Dead Letter Queue for a specific queue.
+     *
+     * @param queue - The name of the queue.
      */
     clearFailed?(queue: string): Promise<void>;
+    /**
+     * Lists all queues managed by this driver.
+     *
+     * Useful for monitoring dashboards to discover active queues dynamically.
+     *
+     * @returns A list of queue names.
+     */
+    getQueues?(): Promise<string[]>;
 }
 
 /**
- * Queueable interface.
+ * Configuration for a recurring scheduled job.
  *
- * Classes implementing this interface can be pushed to a queue for execution.
- * Provides a fluent API for queue/connection/delay configuration.
+ * Defines the schedule (CRON), the job to execute, and metadata tracking execution times.
  *
+ * @public
+ * @since 3.0.0
  * @example
  * ```typescript
- * class MyJob implements Queueable {
- *   queueName?: string
- *   connectionName?: string
- *   delaySeconds?: number
- *
- *   onQueue(queue: string): this {
- *     this.queueName = queue
- *     return this
- *   }
- *
- *   onConnection(connection: string): this {
- *     this.connectionName = connection
- *     return this
- *   }
- *
- *   delay(seconds: number): this {
- *     this.delaySeconds = seconds
- *     return this
- *   }
- * }
+ * const config: ScheduledJobConfig = {
+ *   id: 'daily-report',
+ *   cron: '0 0 * * *',
+ *   queue: 'reports',
+ *   job: serializedJob,
+ *   enabled: true
+ * };
  * ```
  */
-interface Queueable {
-    /**
-     * Queue name where the job should be pushed.
-     */
-    queueName?: string;
-    /**
-     * Connection name the job should use.
-     */
-    connectionName?: string;
-    /**
-     * Delay before execution (seconds).
-     */
-    delaySeconds?: number;
-    /**
-     * Job priority.
-     */
-    priority?: string | number;
-    /**
-     * Set target queue.
-     * @param queue - Queue name
-     * @returns Self for fluent chaining
-     */
-    onQueue(queue: string): this;
-    /**
-     * Set target connection.
-     * @param connection - Connection name
-     * @returns Self for fluent chaining
-     */
-    onConnection(connection: string): this;
-    /**
-     * Set job priority.
-     * @param priority - Priority level
-     * @returns Self for fluent chaining
-     */
-    withPriority(priority: string | number): this;
-    /**
-     * Set delay (seconds).
-     * @param delay - Delay seconds
-     * @returns Self for fluent chaining
-     */
-    delay(delay: number): this;
+interface ScheduledJobConfig {
+    /** Unique identifier for the scheduled task. */
+    id: string;
+    /** Cron expression defining the schedule (e.g., '* * * * *'). */
+    cron: string;
+    /** The target queue name where the job should be pushed. */
+    queue: string;
+    /** The serialized job data. */
+    job: SerializedJob;
+    /** Timestamp of the last successful execution in milliseconds. */
+    lastRun?: number;
+    /** Timestamp of the next scheduled execution in milliseconds. */
+    nextRun?: number;
+    /** Whether the scheduled job is active. */
+    enabled: boolean;
 }
-
 /**
- * Base Job.
+ * Configuration options for the Scheduler.
  *
- * All tasks that should be pushed to a queue should extend this class.
- * Implements the `Queueable` interface, providing a fluent API for queue/connection/delay.
+ * Defines behavior for scheduling tasks, including distributed lock settings.
  *
+ * @public
+ * @since 3.1.0
  * @example
  * ```typescript
- * class SendWelcomeEmail extends Job {
- *   constructor(private userId: string) {
- *     super()
- *   }
- *
- *   async handle(): Promise<void> {
- *     const user = await User.find(this.userId)
- *     await mail.send(new WelcomeEmail(user))
- *   }
- * }
- *
- * // Usage
- * await queue.push(new SendWelcomeEmail('123'))
- *   .onQueue('emails')
- *   .delay(60)
+ * const options: SchedulerOptions = {
+ *   prefix: 'myapp:queue:',
+ *   lockTtl: 60000,        // Lock held for 60 seconds
+ *   lockRefreshInterval: 20000  // Auto-renew every 20 seconds
+ * };
  * ```
- * @public
  */
-declare abstract class Job implements Queueable {
-    /**
-     * Unique job identifier.
-     */
-    id?: string;
-    /**
-     * Queue name.
-     */
-    queueName?: string;
-    /**
-     * Connection name.
-     */
-    connectionName?: string;
-    /**
-     * Delay before execution (seconds).
-     */
-    delaySeconds?: number;
-    /**
-     * Current attempt number.
-     */
-    attempts?: number;
-    /**
-     * Maximum attempts.
-     */
-    maxAttempts?: number;
-    /**
-     * Group ID for FIFO.
-     */
-    groupId?: string;
-    /**
-     * Job priority.
-     */
-    priority?: string | number;
-    /**
-     * Initial retry delay (seconds).
-     */
-    retryAfterSeconds?: number;
-    /**
-     * Retry delay multiplier.
-     */
-    retryMultiplier?: number;
-    /**
-     * Set target queue.
-     */
-    onQueue(queue: string): this;
-    /**
-     * Set target connection.
-     */
-    onConnection(connection: string): this;
+interface SchedulerOptions {
     /**
-     * Set job priority.
-     * @param priority - 'high', 'low', or number
+     * Prefix for Redis keys.
+     *
+     * @default 'queue:'
      */
-    withPriority(priority: string | number): this;
+    prefix?: string;
     /**
-     * Set delay (seconds).
+     * Time-to-live for the distributed lock in milliseconds.
+     *
+     * Setting a longer TTL ensures long-running tasks are not executed repeatedly
+     * due to lock expiration. Recommended to be 2-3 times the expected execution time.
+     *
+     * @default 60000 (60 seconds)
      */
-    delay(delay: number): this;
+    lockTtl?: number;
     /**
-     * Set retry backoff strategy.
-     * @param seconds - Initial delay in seconds
-     * @param multiplier - Multiplier for each subsequent attempt (default: 2)
+     * Interval for automatic lock renewal in milliseconds.
+     *
+     * If set, the lock will be automatically extended every `lockRefreshInterval`.
+     * Recommended to be 1/3 of `lockTtl`.
+     *
+     * @default 20000 (20 seconds)
      */
-    backoff(seconds: number, multiplier?: number): this;
+    lockRefreshInterval?: number;
     /**
-     * Calculate retry delay for the next attempt.
-     * @param attempt - Current attempt number (1-based)
-     * @returns Delay in milliseconds
+     * Number of retries when acquiring a lock fails.
+     *
+     * @default 0
      */
-    getRetryDelay(attempt: number): number;
+    lockRetryCount?: number;
     /**
-     * Job handler logic.
+     * Delay between lock acquisition retries in milliseconds.
      *
-     * Subclasses must implement this method.
+     * @default 100
      */
-    abstract handle(): Promise<void>;
+    lockRetryDelay?: number;
     /**
-     * Failure handler (optional).
+     * The interval in milliseconds at which the scheduler checks for due tasks.
      *
-     * Called when the job fails and reaches the maximum number of attempts.
-     * Subclasses can override to implement custom failure handling.
+     * @default 60000 (1 minute)
+     */
+    tickInterval?: number;
+    /**
+     * The time-to-live for the leader lock in milliseconds.
      *
-     * @param error - Error instance
+     * Ensures that only one node acts as the scheduler leader.
+     * @default 30000 (30 seconds)
      */
-    failed(_error: Error): Promise<void>;
+    leaderTtl?: number;
 }
-
 /**
- * Configuration for a recurring scheduled job.
+ * Manages recurring tasks and cron jobs.
+ *
+ * The Scheduler allows you to register jobs to run at specific intervals using CRON syntax.
+ * It uses Redis (or a compatible driver) to coordinate distributed execution, ensuring that
+ * a scheduled job runs only once per interval across multiple scheduler instances.
  *
  * @public
  * @since 3.0.0
- */
-interface ScheduledJobConfig {
-    /** Unique identifier for the scheduled task. */
-    id: string;
-    /** Cron expression defining the schedule (e.g., '* * * * *'). */
-    cron: string;
-    /** The target queue name where the job should be pushed. */
-    queue: string;
-    /** The serialized job data. */
-    job: SerializedJob;
-    /** Timestamp of the last successful execution in milliseconds. */
-    lastRun?: number;
-    /** Timestamp of the next scheduled execution in milliseconds. */
-    nextRun?: number;
-    /** Whether the scheduled job is active. */
-    enabled: boolean;
-}
-/**
- * Scheduler manages recurring (cron) jobs in Gravito.
- *
- * It uses Redis to store schedule metadata and coordinates distributed
- * execution using locks to ensure jobs are triggered exactly once per interval.
- *
  * @example
  * ```typescript
- * const scheduler = new Scheduler(queueManager);
+ * const scheduler = manager.getScheduler();
  * await scheduler.register({
- *   id: 'daily-cleanup',
- *   cron: '0 0 * * *',
- *   queue: 'default',
- *   job: myJob.serialize()
+ *   id: 'cleanup',
+ *   cron: '0 * * * *', // Every hour
+ *   job: new CleanupJob()
  * });
- * ```
  *
- * @public
- * @since 3.0.0
+ * // Automatically start the scheduler loop
+ * await scheduler.start();
+ * ```
  */
 declare class Scheduler {
     private manager;
     private prefix;
-    constructor(manager: QueueManager, options?: {
-        prefix?: string;
-    });
+    private lockTtl;
+    private lockRefreshInterval?;
+    private lockRetryCount;
+    private lockRetryDelay;
+    private tickInterval;
+    private leaderTtl;
+    private distributedLock?;
+    private running;
+    private timer;
+    private isLeader;
+    constructor(manager: QueueManager, options?: SchedulerOptions);
     private get client();
     /**
-     * Register a scheduled job.
+     * Gets or creates the distributed lock instance.
+     *
+     * @private
+     */
+    private getDistributedLock;
+    /**
+     * Registers a new scheduled job or updates an existing one.
+     *
+     * Calculates the next run time based on the CRON expression and stores the configuration in Redis.
+     *
+     * @param config - The job configuration (excluding nextRun and enabled status which are auto-set).
+     * @throws {Error} If Redis client does not support pipelining.
      */
     register(config: Omit<ScheduledJobConfig, 'nextRun' | 'enabled'>): Promise<void>;
     /**
-     * Remove a scheduled job.
+     * Removes a scheduled job.
+     *
+     * Deletes the job metadata and schedule entry from Redis.
+     *
+     * @param id - The unique identifier of the scheduled job.
      */
     remove(id: string): Promise<void>;
     /**
-     * List all scheduled jobs.
+     * Lists all registered scheduled jobs.
+     *
+     * @returns An array of all scheduled job configurations.
      */
     list(): Promise<ScheduledJobConfig[]>;
     /**
-     * Run a scheduled job immediately (out of schedule).
+     * Starts the automatic scheduler loop.
+     *
+     * Periodically triggers `tick()` to process due jobs. Uses leader election
+     * to ensure that only one node performs the scanning in a multi-node environment.
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the automatic scheduler loop.
+     */
+    stop(): Promise<void>;
+    /**
+     * Acquires the leader lock and performs a tick.
+     *
+     * @private
+     */
+    private performTickWithLeaderElection;
+    /**
+     * Releases the leader lock.
+     *
+     * @private
+     */
+    private releaseLeader;
+    /**
+     * Manually triggers a scheduled job immediately.
+     *
+     * Forces execution of the job regardless of its schedule, without affecting the next scheduled run time.
+     *
+     * @param id - The unique identifier of the scheduled job.
      */
     runNow(id: string): Promise<void>;
     /**
-     * Process due tasks (TICK).
-     * This should be called periodically (e.g. every minute).
+     * Checks for and triggers tasks that are due for execution.
+     *
+     * This method should be called periodically (e.g., via a system cron or a dedicated tick loop).
+     * It scans the schedule for tasks with `nextRun <= now`, acquires a distributed lock for each,
+     * pushes them to their queue, and updates the `nextRun` time.
+     *
+     * The distributed lock ensures that in a multi-node environment, each scheduled job is executed
+     * only once per interval, even if multiple scheduler instances are running.
+     *
+     * @returns The number of jobs triggered in this tick.
      */
     tick(): Promise<number>;
 }
@@ -741,54 +1319,53 @@ declare class Scheduler {
 /**
  * Job serializer interface.
  *
- * Responsible for serializing and deserializing jobs.
- * Supports multiple strategies (JSON, class-name, etc.).
+ * Defines the contract for serializing job objects into storage-friendly formats
+ * (strings/buffers) and deserializing them back into executable Job instances.
  *
+ * @public
  * @example
  * ```typescript
- * class MySerializer implements JobSerializer {
- *   serialize(job: Job): SerializedJob {
- *     // serialization logic
- *   }
- *
- *   deserialize(serialized: SerializedJob): Job {
- *     // deserialization logic
- *   }
+ * class JSONSerializer implements JobSerializer {
+ *   serialize(job) { return { ...job, data: JSON.stringify(job) }; }
+ *   deserialize(serialized) { return JSON.parse(serialized.data); }
  * }
  * ```
  */
 interface JobSerializer {
     /**
-     * Serialize a job.
-     * @param job - Job instance
-     * @returns Serialized job payload
+     * Converts a Job instance into a serializable object.
+     *
+     * @param job - The job instance to serialize.
+     * @returns A `SerializedJob` object containing the data payload and metadata.
      */
     serialize(job: Job): SerializedJob;
     /**
-     * Deserialize a job.
-     * @param serialized - Serialized job payload
-     * @returns Job instance
+     * Reconstructs a Job instance from a serialized object.
+     *
+     * @param serialized - The serialized job data.
+     * @returns A fully hydrated Job instance ready for execution.
      */
     deserialize(serialized: SerializedJob): Job;
 }
 
 /**
- * Queue Manager
+ * The central manager for queue operations.
  *
- * Manages multiple queue connections and drivers, exposing a unified API for pushing and consuming jobs.
- * Supports lazy-loading drivers to keep the core lightweight.
+ * This class manages multiple queue connections and drivers, exposing a unified API for pushing,
+ * popping, and managing jobs. It handles connection pooling, serialization, persistence,
+ * and driver lazy-loading.
  *
+ * @public
  * @example
  * ```typescript
  * const manager = new QueueManager({
- *   default: 'database',
+ *   default: 'redis',
  *   connections: {
- *     database: { driver: 'database', table: 'jobs' },
- *     redis: { driver: 'redis', url: 'redis://...' }
+ *     redis: { driver: 'redis', client: redisClient }
  *   }
- * })
+ * });
  *
- * await manager.push(new SendEmail('user@example.com'))
+ * await manager.push(new SendEmailJob('hello@example.com'));
  * ```
  */
 declare class QueueManager {
@@ -805,420 +1382,1138 @@ declare class QueueManager {
      */
     private log;
     /**
-     * Register a connection.
-     * @param name - Connection name
-     * @param config - Connection config
+     * Registers a new queue connection with the manager.
+     *
+     * Dynamically loads the required driver implementation based on the configuration.
+     *
+     * @param name - The name of the connection (e.g., 'primary').
+     * @param config - The configuration object for the driver.
+     * @throws {Error} If the driver type is missing required dependencies or unsupported.
+     *
+     * @example
+     * ```typescript
+     * manager.registerConnection('analytics', { driver: 'sqs', client: sqs });
+     * ```
      */
     registerConnection(name: string, config: QueueConnectionConfig): void;
     /**
-     * Get a driver for a connection.
-     * @param connection - Connection name
-     * @returns Driver instance
+     * Retrieves the driver instance for a specific connection.
+     *
+     * @param connection - The name of the connection.
+     * @returns The configured QueueDriver instance.
+     * @throws {Error} If the connection has not been registered.
+     *
+     * @example
+     * ```typescript
+     * const driver = manager.getDriver('redis');
+     * ```
      */
     getDriver(connection: string): QueueDriver;
     /**
-     * Get the default connection name.
-     * @returns Default connection name
+     * Gets the name of the default connection.
+     *
+     * @returns The default connection name.
      */
     getDefaultConnection(): string;
     /**
-     * Get a serializer.
-     * @param type - Serializer type
-     * @returns Serializer instance
+     * Retrieves a serializer instance by type.
+     *
+     * @param type - The serializer type (e.g., 'json', 'class'). If omitted, returns the default serializer.
+     * @returns The JobSerializer instance.
+     * @throws {Error} If the requested serializer type is not found.
      */
     getSerializer(type?: string): JobSerializer;
     /**
-     * Register Job classes (used by ClassNameSerializer).
-     * @param jobClasses - Job class array
+     * Registers Job classes for the `ClassNameSerializer`.
+     *
+     * This is required when using 'class' serialization to allow proper hydration of job instances
+     * upon deserialization.
+     *
+     * @param jobClasses - An array of Job class constructors.
+     *
+     * @example
+     * ```typescript
+     * manager.registerJobClasses([SendEmailJob, ProcessOrderJob]);
+     * ```
+     */
+    registerJobClasses(jobClasses: Array<new (...args: unknown[]) => Job>): void;
+    /**
+     * Pushes a single job to the queue.
+     *
+     * Serializes the job, selects the appropriate driver based on job configuration,
+     * and dispatches it. Also handles audit logging if persistence is enabled.
+     *
+     * @template T - The type of the job (extends Job).
+     * @param job - The job instance to enqueue.
+     * @param options - Optional overrides for push behavior (priority, delay, etc.).
+     * @returns The same job instance (for chaining).
+     *
+     * @example
+     * ```typescript
+     * await manager.push(new SendEmailJob('user@example.com'));
+     * ```
+     */
+    push<T extends Job & Queueable>(job: T, options?: JobPushOptions): Promise<T>;
+    /**
+     * Pushes multiple jobs to the queue in a batch.
+     *
+     * Optimizes network requests by batching jobs where possible. Groups jobs by connection
+     * and queue to maximize throughput.
+     *
+     * @template T - The type of the jobs.
+     * @param jobs - An array of job instances to enqueue.
+     * @param options - Configuration for batch size and concurrency.
+     * @returns A promise that resolves when all jobs have been pushed.
+     *
+     * @example
+     * ```typescript
+     * await manager.pushMany(jobs, { batchSize: 500, concurrency: 5 });
+     * ```
+     */
+    pushMany<T extends Job & Queueable>(jobs: T[], options?: {
+        batchSize?: number;
+        concurrency?: number;
+    }): Promise<void>;
+    /**
+     * Pops a single job from the queue.
+     *
+     * Retrieves the next available job from the specified queue.
+     *
+     * @param queue - The queue name (default: 'default').
+     * @param connection - The connection name (defaults to default connection).
+     * @returns A Job instance if found, or `null` if the queue is empty.
+     *
+     * @example
+     * ```typescript
+     * const job = await manager.pop('priority-queue');
+     * if (job) await job.handle();
+     * ```
+     */
+    pop(queue?: string, connection?: string): Promise<Job | null>;
+    /**
+     * Pops multiple jobs from the queue efficiently.
+     *
+     * Attempts to retrieve a batch of jobs from the driver. If the driver does not support
+     * batching, it falls back to sequential popping.
+     *
+     * @param queue - The queue name (default: 'default').
+     * @param count - The maximum number of jobs to retrieve (default: 10).
+     * @param connection - The connection name.
+     * @returns An array of Job instances.
+     *
+     * @example
+     * ```typescript
+     * const jobs = await manager.popMany('default', 50);
+     * ```
+     */
+    popMany(queue?: string, count?: number, connection?: string): Promise<Job[]>;
+    /**
+     * Retrieves the current size of a queue.
+     *
+     * @param queue - The queue name (default: 'default').
+     * @param connection - The connection name.
+     * @returns The number of waiting jobs.
+     *
+     * @example
+     * ```typescript
+     * const count = await manager.size('emails');
+     * ```
+     */
+    size(queue?: string, connection?: string): Promise<number>;
+    /**
+     * Pops a job from the queue with blocking (wait) behavior.
+     *
+     * Waits for a job to become available for the specified timeout duration.
+     * Useful for reducing polling loop frequency.
+     *
+     * @param queues - A queue name or array of queue names to listen to.
+     * @param timeout - Timeout in seconds (0 = block indefinitely).
+     * @param connection - The connection name.
+     * @returns A Job instance if found, or `null` if timed out.
+     *
+     * @example
+     * ```typescript
+     * // Wait up to 30 seconds for a job
+     * const job = await manager.popBlocking('default', 30);
+     * ```
+     */
+    popBlocking(queues?: string | string[], timeout?: number, connection?: string): Promise<Job | null>;
+    /**
+     * Removes all jobs from a specific queue.
+     *
+     * @param queue - The queue name to purge.
+     * @param connection - The connection name.
+     *
+     * @example
+     * ```typescript
+     * await manager.clear('test-queue');
+     * ```
+     */
+    clear(queue?: string, connection?: string): Promise<void>;
+    /**
+     * Retrieves comprehensive statistics for a queue.
+     *
+     * Includes counts for pending, processing, delayed, and failed jobs.
+     *
+     * @param queue - The queue name.
+     * @param connection - The connection name.
+     * @returns A QueueStats object.
+     *
+     * @example
+     * ```typescript
+     * const stats = await manager.stats('default');
+     * console.log(stats.size, stats.failed);
+     * ```
+     */
+    stats(queue?: string, connection?: string): Promise<QueueStats>;
+    /**
+     * Marks a job as successfully completed.
+     *
+     * Removes the job from the processing state and optionally archives it.
+     *
+     * @param job - The job instance that finished.
+     *
+     * @example
+     * ```typescript
+     * await manager.complete(job);
+     * ```
+     */
+    complete<T extends Job & Queueable>(job: T): Promise<void>;
+    /**
+     * Marks a job as failed.
+     *
+     * Moves the job to the failed state (Dead Letter Queue) and optionally archives it.
+     * This is typically called after max retry attempts are exhausted.
+     *
+     * @param job - The job instance that failed.
+     * @param error - The error that caused the failure.
+     *
+     * @example
+     * ```typescript
+     * await manager.fail(job, new Error('Something went wrong'));
+     * ```
+     */
+    fail<T extends Job & Queueable>(job: T, error: Error): Promise<void>;
+    /**
+     * Retrieves the configured persistence adapter.
+     *
+     * @returns The PersistenceAdapter instance, or undefined if not configured.
+     */
+    getPersistence(): PersistenceAdapter | undefined;
+    /**
+     * Gets the Scheduler instance associated with this manager.
+     *
+     * The Scheduler handles delayed jobs and periodic tasks.
+     *
+     * @returns The Scheduler instance.
+     */
+    getScheduler(): Scheduler;
+    /**
+     * Retrieves failed jobs from the Dead Letter Queue.
+     *
+     * @param queue - The queue name.
+     * @param start - The starting index (pagination).
+     * @param end - The ending index (pagination).
+     * @param connection - The connection name.
+     * @returns An array of serialized jobs.
+     *
+     * @example
+     * ```typescript
+     * const failedJobs = await manager.getFailed('default', 0, 10);
+     * ```
+     */
+    getFailed(queue: string, start?: number, end?: number, connection?: string): Promise<SerializedJob[]>;
+    /**
+     * Retries failed jobs from the Dead Letter Queue.
+     *
+     * Moves jobs from the failed state back to the active queue for re-processing.
+     *
+     * @param queue - The queue name.
+     * @param count - The number of jobs to retry.
+     * @param connection - The connection name.
+     * @returns The number of jobs successfully retried.
+     *
+     * @example
+     * ```typescript
+     * await manager.retryFailed('default', 5);
+     * ```
+     */
+    retryFailed(queue: string, count?: number, connection?: string): Promise<number>;
+    /**
+     * Clears all failed jobs from the Dead Letter Queue.
+     *
+     * @param queue - The queue name.
+     * @param connection - The connection name.
+     *
+     * @example
+     * ```typescript
+     * await manager.clearFailed('default');
+     * ```
+     */
+    clearFailed(queue: string, connection?: string): Promise<void>;
+    /**
+     * Retrieves high-level statistics across all registered connections and queues.
+     *
+     * Iterates through all drivers and collects metadata to provide a comprehensive
+     * snapshot of the entire queue system's health.
+     *
+     * @returns A promise resolving to a GlobalStats object.
+     */
+    getGlobalStats(): Promise<GlobalStats>;
+}
+
+/**
+ * Configuration options for the BatchConsumer.
+ *
+ * @example
+ * ```typescript
+ * const options: BatchConsumerOptions = {
+ *   batchSize: 50,
+ *   autoAck: false
+ * };
+ * ```
+ */
+interface BatchConsumerOptions {
+    /**
+     * The name of the queue to consume from.
+     * @default 'default'
+     */
+    queue?: string;
+    /**
+     * The connection name to use.
+     * @default The default connection of QueueManager
+     */
+    connection?: string;
+    /**
+     * The number of jobs to try to retrieve in each batch.
+     * @default 10
+     */
+    batchSize?: number;
+    /**
+     * The polling interval in milliseconds when the queue is empty.
+     * @default 1000
+     */
+    pollInterval?: number;
+    /**
+     * Whether to automatically complete jobs after the handler returns successfully.
+     *
+     * If set to `false`, the handler function is responsible for calling `manager.complete()`
+     * or `manager.fail()` for each job.
+     *
+     * @default true
+     */
+    autoAck?: boolean;
+}
+/**
+ * Specialized consumer for processing jobs in bulk.
+ *
+ * Unlike the standard `Consumer` which processes jobs individually (even if fetched in batches),
+ * the `BatchConsumer` passes an array of jobs to a single handler function. This is ideal for
+ * operations that benefit from bulk processing, such as database inserts or API calls that support batching.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const consumer = new BatchConsumer(manager, async (jobs) => {
+ *   // Process 100 jobs at once
+ *   await elasticsearch.bulkIndex(jobs.map(j => j.data));
+ * }, { batchSize: 100 });
+ *
+ * consumer.start();
+ * ```
+ */
+declare class BatchConsumer {
+    private manager;
+    private handler;
+    private running;
+    private options;
+    constructor(manager: QueueManager, handler: (jobs: Job[]) => Promise<void>, options?: BatchConsumerOptions);
+    /**
+     * Starts the batch consuming loop.
+     *
+     * Continuously polls for batches of jobs and passes them to the handler.
      */
-    registerJobClasses(jobClasses: Array<new (...args: unknown[]) => Job>): void;
+    start(): Promise<void>;
     /**
-     * Push a Job to the queue.
+     * Stops the consumer loop.
      *
-     * @template T - The type of the job.
-     * @param job - Job instance to push.
-     * @param options - Push options.
-     * @returns The same job instance (for fluent chaining).
-     *
-     * @example
-     * ```typescript
-     * await manager.push(new SendEmailJob('user@example.com'));
-     * ```
+     * Sets the running flag to false. The loop will exit after the current iteration finishes.
      */
-    push<T extends Job & Queueable>(job: T, options?: JobPushOptions): Promise<T>;
+    stop(): void;
+}
+
+/**
+ * Sandboxed Worker Implementation.
+ *
+ * Executes jobs in isolated Worker Threads to provide context isolation,
+ * error containment, and resource limits.
+ *
+ * @public
+ */
+
+/**
+ * Configuration options for the Sandboxed Worker.
+ */
+interface SandboxedWorkerConfig {
     /**
-     * Push multiple jobs to the queue.
-     *
-     * @template T - The type of the jobs.
-     * @param jobs - Array of job instances.
-     * @param options - Bulk push options.
+     * Maximum execution time for a job in milliseconds.
      *
-     * @example
-     * ```typescript
-     * await manager.pushMany(jobs, { batchSize: 500, concurrency: 2 });
-     * ```
+     * Jobs exceeding this duration will be forcefully terminated.
+     * @default 30000 (30 seconds)
      */
-    pushMany<T extends Job & Queueable>(jobs: T[], options?: {
-        batchSize?: number;
-        concurrency?: number;
-    }): Promise<void>;
+    maxExecutionTime?: number;
     /**
-     * Pop a job from the queue.
+     * Maximum memory limit for the worker in MB.
      *
-     * @param queue - Queue name (default: 'default').
-     * @param connection - Connection name (optional).
-     * @returns Job instance or null if queue is empty.
-     *
-     * @example
-     * ```typescript
-     * const job = await manager.pop('emails');
-     * if (job) await job.handle();
-     * ```
+     * If the worker exceeds this limit, it will be terminated and restarted.
+     * Note: Relies on `resourceLimits` which may vary by platform.
+     * @default undefined (unlimited)
      */
-    pop(queue?: string, connection?: string): Promise<Job | null>;
+    maxMemory?: number;
     /**
-     * Pop multiple jobs from the queue.
+     * Whether to isolate contexts for each job.
      *
-     * @param queue - Queue name (default: 'default').
-     * @param count - Number of jobs to pop (default: 10).
-     * @param connection - Connection name (optional).
-     * @returns Array of Job instances.
+     * If `true`, a new Worker Thread is created for every job execution.
+     * If `false`, the Worker Thread is reused across multiple jobs.
+     * @default false
      */
-    popMany(queue?: string, count?: number, connection?: string): Promise<Job[]>;
+    isolateContexts?: boolean;
     /**
-     * Get queue size.
+     * Idle timeout for the Worker Thread in milliseconds.
      *
-     * @param queue - Queue name (default: 'default').
-     * @param connection - Connection name (optional).
-     * @returns Number of jobs in the queue.
+     * The worker will be terminated if it remains idle for this duration to save resources.
+     * @default 60000 (60 seconds)
      */
-    size(queue?: string, connection?: string): Promise<number>;
-    /**
-     * Pop a job from the queue (blocking).
+    idleTimeout?: number;
+}
+/**
+ * Sandboxed Worker.
+ *
+ * Manages the lifecycle of a Node.js Worker Thread for job execution.
+ * Provides features like:
+ * - Context Isolation: Run code in a separate thread.
+ * - Timeout Enforcement: Terminate hangs or long-running jobs.
+ * - Memory Limits: Prevent OOM issues affecting the main process.
+ * - Error Containment: Worker crashes do not crash the main application.
+ *
+ * @example
+ * ```typescript
+ * const worker = new SandboxedWorker({
+ *   maxExecutionTime: 30000,
+ *   maxMemory: 512,
+ *   isolateContexts: true
+ * });
+ *
+ * await worker.execute(serializedJob);
+ * await worker.terminate();
+ * ```
+ */
+declare class SandboxedWorker {
+    private worker;
+    private state;
+    private config;
+    private idleTimer;
+    private executionTimer;
+    /**
+     * Creates a SandboxedWorker instance.
      *
-     * @param queue - Queue name (default: 'default').
-     * @param timeout - Timeout in seconds (default: 0, wait forever).
-     * @param connection - Connection name (optional).
+     * @param config - Configuration options for the worker.
      */
-    popBlocking(queues?: string | string[], timeout?: number, connection?: string): Promise<Job | null>;
+    constructor(config?: SandboxedWorkerConfig);
     /**
-     * Clear all jobs from a queue.
+     * Initializes the Worker Thread.
      *
-     * @param queue - Queue name (default: 'default').
-     * @param connection - Connection name (optional).
+     * @returns The active Worker Thread instance.
+     * @throws {Error} If worker initialization fails or times out.
      */
-    clear(queue?: string, connection?: string): Promise<void>;
+    private initWorker;
     /**
-     * Get queue statistics including size, delayed, and failed job counts.
+     * Executes a job in the sandboxed environment.
      *
-     * @param queue - Queue name (default: 'default').
-     * @param connection - Connection name (optional).
-     * @returns Queue statistics object.
+     * @param job - The serialized job data to execute.
+     * @throws {Error} If execution fails, times out, or the worker crashes.
      */
-    stats(queue?: string, connection?: string): Promise<QueueStats>;
+    execute(job: SerializedJob): Promise<void>;
     /**
-     * Mark a job as completed.
-     * @param job - Job instance
+     * Internal method to send execution message to the worker thread.
+     *
+     * @param worker - The worker thread instance.
+     * @param job - Job data.
      */
-    complete<T extends Job & Queueable>(job: T): Promise<void>;
+    private executeInWorker;
     /**
-     * Mark a job as permanently failed.
-     * @param job - Job instance
-     * @param error - Error object
+     * Creates a promise that rejects after the configured timeout.
      */
-    fail<T extends Job & Queueable>(job: T, error: Error): Promise<void>;
+    private createTimeoutPromise;
     /**
-     * Get the persistence adapter if configured.
+     * Starts the idle timer to auto-terminate the worker.
      */
-    getPersistence(): PersistenceAdapter | undefined;
+    private startIdleTimer;
     /**
-     * Get the scheduler if configured.
+     * Terminates the Worker Thread immediately.
+     *
+     * Stops any running job and releases resources.
      */
-    getScheduler(): Scheduler;
+    terminate(): Promise<void>;
     /**
-     * Get failed jobs from DLQ (if driver supports it).
+     * Gets the current state of the worker.
+     *
+     * @returns The current `WorkerState`.
      */
-    getFailed(queue: string, start?: number, end?: number, connection?: string): Promise<SerializedJob[]>;
+    getState(): string;
     /**
-     * Retry failed jobs from DLQ (if driver supports it).
+     * Checks if the worker is ready to accept a job.
+     *
+     * @returns `true` if ready, `false` otherwise.
      */
-    retryFailed(queue: string, count?: number, connection?: string): Promise<number>;
+    isReady(): boolean;
     /**
-     * Clear failed jobs from DLQ (if driver supports it).
+     * Checks if the worker is currently executing a job.
+     *
+     * @returns `true` if busy, `false` otherwise.
      */
-    clearFailed(queue: string, connection?: string): Promise<void>;
+    isBusy(): boolean;
 }
 
 /**
- * Worker options.
+ * Configuration options for the Worker.
+ *
+ * Controls the execution behavior of jobs, including retry limits and timeouts.
+ *
+ * @example
+ * ```typescript
+ * const options: WorkerOptions = {
+ *   maxAttempts: 3,
+ *   timeout: 30
+ * };
+ * ```
  */
 interface WorkerOptions {
     /**
-     * Maximum retry attempts.
+     * The maximum number of attempts for a job before it is marked as failed.
+     *
+     * This value serves as a default fallback if the job itself does not specify `maxAttempts`.
      */
     maxAttempts?: number;
     /**
-     * Job timeout (seconds).
+     * The maximum execution time for a job in seconds.
+     *
+     * If the job exceeds this duration, it will be timed out and marked as failed.
      */
     timeout?: number;
     /**
-     * Failure callback.
+     * Callback function triggered when a job permanently fails.
+     *
+     * This allows for custom error reporting or cleanup logic outside of the job class.
      */
     onFailed?: (job: Job, error: Error) => Promise<void>;
+    /**
+     * Enable sandboxed execution using Worker Threads.
+     *
+     * When enabled, jobs are executed in isolated Worker Threads, providing:
+     * - Context isolation: Each job runs in a separate execution environment
+     * - Crash protection: Worker crashes don't affect the main thread
+     * - Memory limits: Prevent memory leaks from affecting the main process
+     * - Timeout enforcement: Jobs exceeding the timeout are forcefully terminated
+     *
+     * @default false
+     */
+    sandboxed?: boolean;
+    /**
+     * Sandboxed worker configuration options.
+     *
+     * Only used when `sandboxed` is true.
+     */
+    sandboxConfig?: SandboxedWorkerConfig;
 }
 /**
- * Base Worker.
+ * Executes background jobs.
  *
- * Responsible for executing `Job` instances.
- * Provides error handling, retry logic, and timeout support.
+ * The Worker is responsible for running the `handle()` method of a job, managing its lifecycle,
+ * enforcing timeouts, and handling retries or failures.
+ *
+ * Supports two execution modes:
+ * - **Standard Mode** (default): Executes jobs directly in the current process
+ * - **Sandboxed Mode**: Executes jobs in isolated Worker Threads for enhanced security and stability
  *
  * @example
  * ```typescript
+ * // Standard mode
  * const worker = new Worker({
  *   maxAttempts: 3,
  *   timeout: 60
- * })
+ * });
+ *
+ * // Sandboxed mode
+ * const sandboxedWorker = new Worker({
+ *   maxAttempts: 3,
+ *   timeout: 60,
+ *   sandboxed: true,
+ *   sandboxConfig: {
+ *     maxExecutionTime: 30000,
+ *     maxMemory: 512,
+ *     isolateContexts: true
+ *   }
+ * });
  *
- * await worker.process(job)
+ * await worker.process(job);
  * ```
  */
 declare class Worker {
     private options;
+    private sandboxedWorker?;
     constructor(options?: WorkerOptions);
     /**
-     * Process a Job.
-     * @param job - Job instance
+     * Processes a single job instance.
+     *
+     * 1. Checks attempt counts.
+     * 2. Enforces execution timeout (if configured).
+     * 3. Runs `job.handle()` (either directly or in a sandboxed Worker Thread).
+     * 4. Catches errors and invokes failure handlers if max attempts are reached.
+     *
+     * @param job - The job to process.
+     * @throws {Error} If the job execution fails (to trigger retry logic in the consumer).
      */
     process(job: Job): Promise<void>;
     /**
-     * Handle failure.
+     * Processes a job in standard mode (directly in current process).
+     *
+     * @param job - The job to process.
+     * @param timeout - Optional timeout in seconds.
+     */
+    private processStandard;
+    /**
+     * Processes a job in sandboxed mode (in Worker Thread).
+     *
+     * @param job - The job to process.
+     */
+    private processSandboxed;
+    /**
+     * Serializes a Job instance for Worker Thread execution.
+     *
+     * @param job - The job to serialize.
+     * @returns Serialized job data.
+     */
+    private serializeJob;
+    /**
+     * Handles the permanent failure of a job.
+     *
+     * Invokes the job's `failed()` method and any global `onFailed` callback.
+     *
+     * @param job - The failed job.
+     * @param error - The error that caused the failure.
      */
     private handleFailure;
+    /**
+     * Terminates the sandboxed worker and releases resources.
+     *
+     * Should be called when the worker is no longer needed.
+     * Only applicable when running in sandboxed mode.
+     */
+    terminate(): Promise<void>;
 }
 
 /**
- * Consumer options.
+ * Configuration options for the Consumer.
+ *
+ * Defines which queues to listen to, connection settings, concurrency levels,
+ * and advanced behavior like rate limiting and batch processing.
+ *
+ * @example
+ * ```typescript
+ * const options: ConsumerOptions = {
+ *   queues: ['emails', 'notifications'],
+ *   concurrency: 5,
+ *   pollInterval: 2000
+ * };
+ * ```
  */
 interface ConsumerOptions {
     /**
-     * Queues to listen on.
+     * List of queue names to consume jobs from.
+     *
+     * The consumer will poll these queues in the order provided or based on driver logic.
      */
     queues: string[];
     /**
-     * Connection name.
+     * The connection name to use (e.g., 'redis', 'sqs').
+     *
+     * If not provided, uses the default connection from QueueManager.
      */
     connection?: string;
     /**
-     * Worker options.
+     * Configuration options passed to the underlying Worker.
      */
     workerOptions?: WorkerOptions;
     /**
-     * Polling interval (milliseconds).
+     * The interval in milliseconds to wait before polling again when the queue is empty.
      */
     pollInterval?: number;
     /**
-     * Whether to keep polling when queues are empty.
+     * Whether to keep the process alive when queues are empty.
+     *
+     * If false, the consumer will exit the loop when no jobs are found (useful for one-off scripts).
      */
     keepAlive?: boolean;
     /**
-     * Monitoring options.
+     * Monitoring configuration.
+     *
+     * Can be a boolean to enable default monitoring, or an object for advanced configuration.
      */
     monitor?: boolean | {
         /**
-         * Heartbeat interval (milliseconds). Default: 5000.
+         * The interval in milliseconds for sending heartbeat updates.
+         * @default 5000
          */
         interval?: number;
         /**
-         * Extra info to report with heartbeat.
+         * Additional metadata to include in heartbeat payloads.
          */
         extraInfo?: Record<string, unknown>;
         /**
-         * Prefix for monitoring keys/channels.
+         * Key prefix for monitoring events (e.g. for Redis Pub/Sub).
          */
         prefix?: string;
     };
     /**
-     * Rate limits per queue.
-     * Example: { 'emails': { max: 10, duration: 1000 } }
+     * Rate limiting configuration per queue.
+     *
+     * Defines the maximum number of jobs to process within a given duration.
+     *
+     * @example
+     * ```typescript
+     * { 'emails': { max: 10, duration: 1000 } } // 10 emails per second
+     * ```
      */
     rateLimits?: Record<string, {
         max: number;
         duration: number;
     }>;
     /**
-     * Max concurrent jobs to process. Default: 1.
+     * The maximum number of jobs to process concurrently.
+     *
+     * @default 1
      */
     concurrency?: number;
     /**
-     * Whether to process jobs with the same groupId sequentially.
-     * If true, jobs with the same groupId will never run concurrently,
-     * regardless of the global concurrency setting.
+     * Whether to enforce sequential processing for jobs with the same `groupId`.
+     *
+     * If true, jobs sharing a `groupId` will be processed one after another,
+     * even if global concurrency is high.
+     *
      * @default true
      */
     groupJobsSequential?: boolean;
     /**
-     * Minimum polling interval in ms (for adaptive polling).
+     * The minimum polling interval in milliseconds for adaptive polling.
+     *
      * @default 100
      */
     minPollInterval?: number;
     /**
-     * Maximum polling interval in ms (for adaptive polling).
+     * The maximum polling interval in milliseconds for adaptive polling.
+     *
      * @default 5000
      */
     maxPollInterval?: number;
     /**
-     * Backoff multiplier for adaptive polling.
+     * The multiplier used to increase the polling interval when the queue is empty.
+     *
      * @default 1.5
      */
     backoffMultiplier?: number;
     /**
-     * Batch size for consuming jobs.
-     * If > 1, tries to fetch multiple jobs at once.
+     * The number of jobs to try to fetch in a single request.
+     *
+     * If supported by the driver, fetching multiple jobs reduces network round-trips.
+     *
      * @default 1
      */
     batchSize?: number;
     /**
-     * Whether to use blocking pop (BLPOP/long-polling) if supported by driver.
-     * Only applies when batchSize is 1.
+     * Whether to use blocking operations (like BLPOP in Redis) when polling.
+     *
+     * Significant optimization for low-latency job pickup. Only applies when `batchSize` is 1.
+     *
      * @default true
      */
     useBlocking?: boolean;
     /**
-     * Timeout in seconds for blocking pop.
+     * The timeout in seconds for blocking operations.
+     *
      * @default 5
      */
     blockingTimeout?: number;
     /**
-     * Enable verbose debug logging.
+     * Enable verbose debug logging for consumer activities.
+     *
      * @default false
      */
     debug?: boolean;
+    /**
+     * 最大處理請求數量。
+     *
+     * 當 consumer 處理完這個數量的 job 後會自動停止（觸發 max_requests_reached 事件）。
+     * 適用於需要定期重啟 worker 的場景（避免記憶體累積、載入最新程式碼等）。
+     *
+     * @default undefined (無限制)
+     */
+    maxRequests?: number;
+    /**
+     * Optional event callback for external monitoring systems.
+     *
+     * Called whenever a job lifecycle event occurs (started, processed, failed, etc.).
+     */
+    onEvent?: (event: string, payload: any) => void;
 }
 /**
- * Consumer
+ * The Consumer responsible for processing jobs from the queue.
  *
- * Consumes and executes jobs from queues.
- * Supports embedded mode (inside the main app) and standalone mode (as a worker service).
+ * It polls the configured queues, retrieves jobs, and delegates execution to a `Worker`.
+ * It handles concurrency, rate limiting, adaptive polling, and emits lifecycle events
+ * (job:started, job:processed, job:failed, etc.).
  *
+ * @public
  * @example
  * ```typescript
- * // Embedded mode
  * const consumer = new Consumer(queueManager, {
- *   queues: ['default', 'emails'],
- *   pollInterval: 1000
- * })
- *
- * consumer.start()
+ *   queues: ['default'],
+ *   concurrency: 10
+ * });
  *
- * // Standalone mode (CLI)
- * // Start via CLI tooling with graceful shutdown
+ * await consumer.start();
  * ```
  *
  * @emits job:started - When a job begins processing. Payload: { job: Job, queue: string }
  * @emits job:processed - When a job completes successfully. Payload: { job: Job, duration: number, queue: string }
  * @emits job:failed - When a job fails an attempt. Payload: { job: Job, error: Error, duration: number, queue: string }
  * @emits job:retried - When a job is scheduled for a retry. Payload: { job: Job, attempt: number, delay: number }
- * @emits job:failed_permanently - When a job fails all attempts and is moved to DLQ. Payload: { job: Job, error: Error }
+ * @emits job:failed_permanently - When a job fails all attempts. Payload: { job: Job, error: Error }
  */
 declare class Consumer extends EventEmitter {
     private queueManager;
     private options;
+    /**
+     * Group limiter 的存活時間（毫秒）。
+     * 超過此時間未使用的 group limiter 會被清理，避免記憶體洩漏。
+     */
+    private static readonly GROUP_LIMITER_TTL;
     private running;
     private stopRequested;
     private workerId;
     private heartbeatTimer;
+    private cleanupTimer;
     private groupLimiters;
+    private groupLimiterLastUsed;
     private stats;
     constructor(queueManager: QueueManager, options: ConsumerOptions);
     private get connectionName();
     /**
-     * Log debug message.
+     * Logs a debug message if debug mode is enabled.
+     */
+    private log;
+    /**
+     * Starts the consumer loop.
+     *
+     * Begins polling the queues and processing jobs. This method returns a promise that resolves
+     * only when the consumer stops (if `keepAlive` is false) or throws if already running.
+     *
+     * @throws {Error} If the consumer is already running.
+     */
+    start(): Promise<void>;
+    /**
+     * Run a job with concurrency controls and group locking.
+     */
+    private runJob;
+    /**
+     * Delegates the actual processing to the worker and handles stats/logging.
+     */
+    private handleJob;
+    private startHeartbeat;
+    private stopHeartbeat;
+    /**
+     * 清理閒置的 group limiters。
+     *
+     * 定期檢查並移除超過 TTL 且沒有 active/pending jobs 的 group limiters，
+     * 避免記憶體洩漏。
+     */
+    private cleanupGroupLimiters;
+    /**
+     * 啟動 group limiter 清理計時器。
+     */
+    private startCleanupTimer;
+    /**
+     * 停止 group limiter 清理計時器。
+     */
+    private stopCleanupTimer;
+    private publishLog;
+    /**
+     * Gracefully stops the consumer.
+     *
+     * Signals the consumer to stop accepting new jobs and waits for currently running jobs
+     * to complete.
+     *
+     * @returns A promise that resolves when the consumer has fully stopped.
+     */
+    stop(): Promise<void>;
+    /**
+     * Checks if the consumer is currently active.
+     *
+     * @returns True if the consumer loop is running.
+     */
+    isRunning(): boolean;
+    /**
+     * Retrieves current operational statistics.
+     *
+     * @returns An object containing processed, failed, retried, and active job counts.
+     */
+    getStats(): {
+        processed: number;
+        failed: number;
+        retried: number;
+        active: number;
+    };
+    /**
+     * Resets the internal statistics counters.
+     */
+    resetStats(): void;
+}
+
+/**
+ * Bull Queue client interface (compatible with bullmq package).
+ */
+interface BullQueueClient {
+    add(name: string, data: any, options?: any): Promise<any>;
+    getJob(id: string): Promise<any | null>;
+    count(): Promise<number>;
+    process(handler: (job: any) => Promise<void>): void;
+    on(event: string, handler: (...args: any[]) => void): void;
+    off(event: string, handler: (...args: any[]) => void): void;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    clean(grace: number, limit?: number, type?: string): Promise<number>;
+    close(): Promise<void>;
+    getJobCounts(types?: string[]): Promise<Record<string, number>>;
+    getDelayedCount(): Promise<number>;
+    getFailedCount(): Promise<number>;
+    getActiveCount(): Promise<number>;
+    [key: string]: any;
+}
+interface BullWorkerClient {
+    [key: string]: any;
+}
+/**
+ * Bull Queue driver configuration.
+ */
+interface BullMQDriverConfig {
+    /**
+     * Bull Queue instance (from bullmq package).
+     */
+    queue: BullQueueClient;
+    /**
+     * Optional Bull Worker instance for processing jobs.
+     */
+    worker?: BullWorkerClient;
+    /**
+     * Connection options (host, port, etc. for Redis).
+     */
+    connection?: {
+        host?: string;
+        port?: number;
+        password?: string;
+        db?: number;
+        [key: string]: any;
+    };
+    /**
+     * Default number of concurrent workers (default: 1).
+     */
+    concurrency?: number;
+    /**
+     * Key prefix for namespacing queues (default: 'gravito:').
+     */
+    prefix?: string;
+    /**
+     * Enable debug logging.
+     */
+    debug?: boolean;
+}
+/**
+ * Bull Queue driver implementation.
+ *
+ * Provides high-performance, persistent job queuing using Bull Queue (backed by Redis).
+ * Supports priority, delays, retries, and group-based FIFO processing.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * import { Queue } from 'bullmq'
+ * import Redis from 'ioredis'
+ *
+ * const redis = new Redis()
+ * const queue = new Queue('gravito-events', { connection: redis })
+ * const driver = new BullMQDriver({ queue })
+ * ```
+ */
+declare class BullMQDriver implements QueueDriver {
+    private queue;
+    private prefix;
+    private debug;
+    private queueMap;
+    constructor(config: BullMQDriverConfig);
+    /**
+     * Get or create a queue for the given queue name.
+     */
+    private getQueue;
+    /**
+     * Build Job Options from JobPushOptions.
+     */
+    private buildJobOptions;
+    /**
+     * Create Bull job data from SerializedJob.
+     */
+    private createBullJobData;
+    /**
+     * Pushes a job to Bull Queue.
+     */
+    push(queue: string, job: SerializedJob, options?: JobPushOptions): Promise<void>;
+    /**
+     * Pops a job from Bull Queue.
+     * Note: Bull Queue typically uses Workers, not manual pop.
+     * This is a fallback implementation.
+     */
+    pop(queue: string): Promise<SerializedJob | null>;
+    /**
+     * Returns the size of the queue.
+     */
+    size(queue: string): Promise<number>;
+    /**
+     * Clears the queue.
+     */
+    clear(queue: string): Promise<void>;
+    /**
+     * Marks a job as failed (moves to failed list).
      */
-    private log;
+    fail(queue: string, job: SerializedJob): Promise<void>;
     /**
-     * Start the consumer loop.
+     * Returns detailed statistics for the queue.
      */
-    start(): Promise<void>;
+    stats(queue: string): Promise<QueueStats>;
     /**
-     * Run a job with concurrency controls.
+     * Retrieves failed jobs from the Dead Letter Queue.
      */
-    private runJob;
+    getFailed(queue: string, _start?: number, _end?: number): Promise<SerializedJob[]>;
     /**
-     * Handle a single job.
+     * Retries failed jobs.
      */
-    private handleJob;
-    private startHeartbeat;
-    private stopHeartbeat;
-    private publishLog;
+    retryFailed(queue: string, _count?: number): Promise<number>;
     /**
-     * Stop the consumer loop (graceful shutdown).
+     * Clears the Dead Letter Queue.
      */
-    stop(): Promise<void>;
+    clearFailed(queue: string): Promise<void>;
     /**
-     * Check whether the consumer is running.
+     * Creates a new queue/topic.
      */
-    isRunning(): boolean;
+    createTopic(_topic: string, _options?: TopicOptions): Promise<void>;
     /**
-     * Get current consumer statistics.
+     * Deletes a queue/topic.
      */
-    getStats(): {
-        processed: number;
-        failed: number;
-        retried: number;
-        active: number;
-    };
+    deleteTopic(topic: string): Promise<void>;
     /**
-     * Reset statistics counters.
+     * Pushes multiple jobs in batch.
      */
-    resetStats(): void;
+    pushMany(queue: string, jobs: SerializedJob[]): Promise<void>;
+    /**
+     * Pops multiple jobs in batch.
+     */
+    popMany(_queue: string, _count: number): Promise<SerializedJob[]>;
+    /**
+     * Reports worker heartbeat.
+     */
+    reportHeartbeat(workerInfo: {
+        id: string;
+        status: string;
+        hostname: string;
+        pid: number;
+        uptime: number;
+        last_ping: string;
+        queues: string[];
+        metrics?: Record<string, any>;
+        [key: string]: any;
+    }, _prefix?: string): Promise<void>;
+    /**
+     * Publishes a log message.
+     */
+    publishLog(logPayload: {
+        level: string;
+        message: string;
+        workerId: string;
+        jobId?: string;
+        timestamp: string;
+        [key: string]: any;
+    }, _prefix?: string): Promise<void>;
+    /**
+     * Checks rate limit for a queue.
+     */
+    checkRateLimit(_queue: string, _config: {
+        max: number;
+        duration: number;
+    }): Promise<boolean>;
+    /**
+     * Retrieves all queue names.
+     */
+    getQueues(): Promise<string[]>;
 }
 
 /**
  * Generic database service interface.
- * Users should implement this interface with their preferred ORM/database client.
+ *
+ * Adapts any SQL database client (e.g., pg, mysql2, sqlite3) for use with the DatabaseDriver.
+ * Users must provide an implementation of this interface that wraps their specific DB library.
  */
 interface DatabaseService {
     /**
      * Execute a raw SQL query.
-     * @param sql - The SQL query string with placeholders ($1, $2, etc.)
-     * @param bindings - The values to bind to placeholders
+     *
+     * @param sql - The SQL query string with placeholders (e.g., $1, ?).
+     * @param bindings - The values to bind to the placeholders.
+     * @returns The query result (rows or metadata).
      */
     execute<T = unknown>(sql: string, bindings?: unknown[]): Promise<T[] | T>;
     /**
-     * Execute multiple queries within a transaction.
-     * @param callback - The callback to execute within the transaction
+     * Execute multiple queries within a single transaction.
+     *
+     * @param callback - A function that receives a transaction-scoped service instance.
+     * @returns The result of the callback.
      */
     transaction<T>(callback: (tx: DatabaseService) => Promise<T>): Promise<T>;
 }
 /**
- * Database driver configuration.
+ * Configuration options for the DatabaseDriver.
  */
 interface DatabaseDriverConfig {
     /**
-     * Table name (default: `jobs`).
+     * The name of the table used to store jobs.
+     * @default 'jobs'
      */
     table?: string;
     /**
-     * Database service instance that implements DatabaseService interface.
+     * The database service adapter instance.
      */
     dbService?: DatabaseService;
 }
 /**
- * Database Driver
+ * Database-backed queue driver.
  *
- * Uses a database as the queue backend.
- * Works with any database service that implements the DatabaseService interface.
+ * Persists jobs in a SQL database table. Supports delayed jobs, reservation (locking),
+ * and reliable delivery. Compatible with PostgreSQL (SKIP LOCKED), MySQL, and SQLite.
  *
+ * @public
  * @example
  * ```typescript
- * // Create a database service adapter
- * const dbService = {
- *   execute: async (sql, bindings) => yourDbClient.query(sql, bindings),
- *   transaction: async (callback) => yourDbClient.transaction(callback),
- * }
- *
- * const driver = new DatabaseDriver({ dbService, table: 'jobs' })
- * await driver.push('default', serializedJob)
+ * const driver = new DatabaseDriver({
+ *   dbService: myDbAdapter,
+ *   table: 'queue_jobs'
+ * });
  * ```
  */
 declare class DatabaseDriver implements QueueDriver {
@@ -1226,55 +2521,101 @@ declare class DatabaseDriver implements QueueDriver {
     private dbService;
     constructor(config: DatabaseDriverConfig);
     /**
-     * Push a job to a queue.
+     * Pushes a job to the database queue.
+     *
+     * Inserts a new row into the jobs table.
+     *
+     * @param queue - The queue name.
+     * @param job - The serialized job.
      */
     push(queue: string, job: SerializedJob): Promise<void>;
     /**
-     * Pop a job from the queue (FIFO, with delay support).
+     * Pops the next available job from the queue.
+     *
+     * Uses transactional locking (SELECT ... FOR UPDATE SKIP LOCKED if supported) to ensure
+     * atomic reservation of jobs by workers.
+     *
+     * @param queue - The queue name.
+     * @returns The job or `null`.
      */
     pop(queue: string): Promise<SerializedJob | null>;
     /**
-     * Pop multiple jobs from the queue.
+     * Pops multiple jobs from the queue in a single transaction.
+     *
+     * @param queue - The queue name.
+     * @param count - Max jobs to pop.
      */
     popMany(queue: string, count: number): Promise<SerializedJob[]>;
     /**
-     * Get queue statistics.
+     * Retrieves queue statistics by querying the table.
+     *
+     * @param queue - The queue name.
      */
     stats(queue: string): Promise<QueueStats>;
     /**
-     * Get queue size.
+     * Returns the count of pending jobs.
+     *
+     * @param queue - The queue name.
      */
     size(queue: string): Promise<number>;
     /**
-     * Clear a queue.
+     * Clears the queue by deleting all rows for the queue.
+     *
+     * @param queue - The queue name.
      */
     clear(queue: string): Promise<void>;
     /**
-     * Pop a job from the queue (blocking).
-     * Simple polling fallback for databases.
+     * Pops a job using a polling loop (Blocking simulation).
+     *
+     * @param queue - The queue name.
+     * @param timeout - Timeout in seconds.
      */
     popBlocking(queue: string, timeout: number): Promise<SerializedJob | null>;
     /**
-     * Push multiple jobs.
-     * Optimizes by using a single multi-row insert if possible.
+     * Pushes multiple jobs using a transaction.
+     *
+     * @param queue - The queue name.
+     * @param jobs - Array of jobs.
      */
     pushMany(queue: string, jobs: SerializedJob[]): Promise<void>;
     /**
-     * Mark a job as failed (DLQ).
+     * Marks a job as permanently failed by moving it to the DLQ (separate logical queue in DB).
+     *
+     * @param queue - The queue name.
+     * @param job - The failed job.
      */
     fail(queue: string, job: SerializedJob): Promise<void>;
     /**
-     * Acknowledge/Complete a job.
+     * Deletes a job row from the database (completion).
+     *
+     * @param _queue - The queue name (unused).
+     * @param job - The job to complete.
      */
     complete(_queue: string, job: SerializedJob): Promise<void>;
 }
 
+declare class GrpcDriver implements QueueDriver {
+    private client;
+    constructor(config: GrpcDriverConfig);
+    private getCredentials;
+    push(queue: string, job: SerializedJob, options?: JobPushOptions): Promise<void>;
+    pop(queue: string): Promise<SerializedJob | null>;
+    size(queue: string): Promise<number>;
+    clear(queue: string): Promise<void>;
+    acknowledge(messageId: string): Promise<void>;
+    stats(queue: string): Promise<QueueStats>;
+    private toProtoJob;
+    private fromProtoJob;
+}
+
 /**
  * Kafka driver configuration.
  */
 interface KafkaDriverConfig {
     /**
      * Kafka client instance (kafkajs).
+     *
+     * Must provide producer, admin, and consumer factories compatible with KafkaJS.
      */
     client: {
         producer: () => {
@@ -1324,29 +2665,22 @@ interface KafkaDriverConfig {
         };
     };
     /**
-     * Consumer group ID (for consuming messages).
+     * Consumer group ID used for reading messages.
+     * @default 'gravito-workers'
      */
     consumerGroupId?: string;
 }
 /**
- * Kafka Driver
+ * Kafka-backed queue driver.
  *
- * Uses Apache Kafka as the queue backend.
- * Supports topic management, consumer groups, and batch operations.
- *
- * Requires `kafkajs`.
+ * Uses Apache Kafka topics as queues. Designed for high-throughput streaming
+ * rather than traditional job queue semantics (pop/delete).
+ * Supports push-based consumption via `subscribe()`.
  *
+ * @public
  * @example
  * ```typescript
- * import { Kafka } from 'kafkajs'
- *
- * const kafka = new Kafka({
- *   brokers: ['localhost:9092'],
- *   clientId: 'gravito-app'
- * })
- *
- * const driver = new KafkaDriver({ client: kafka, consumerGroupId: 'workers' })
- * await driver.push('default', serializedJob)
+ * const driver = new KafkaDriver({ client: kafka, consumerGroupId: 'my-app' });
  * ```
  */
 declare class KafkaDriver implements QueueDriver {
@@ -1364,63 +2698,86 @@ declare class KafkaDriver implements QueueDriver {
      */
     private ensureAdmin;
     /**
-     * Push a job to a topic.
+     * Pushes a job to a Kafka topic.
+     *
+     * @param queue - The topic name.
+     * @param job - The job to publish.
      */
     push(queue: string, job: SerializedJob): Promise<void>;
     /**
-     * Pop is not supported for Kafka.
+     * Pop is not supported for Kafka (Push-based).
      *
-     * Note: Kafka uses a push-based model, so you should use `subscribe()`.
+     * Kafka consumers typically stream messages. Use `subscribe()` instead.
+     *
+     * @throws {Error} Always throws as Kafka does not support polling individual messages in this manner.
      */
     pop(_queue: string): Promise<SerializedJob | null>;
     /**
-     * Kafka does not provide a direct queue size.
+     * Returns 0 as Kafka does not expose a simple "queue size".
      *
-     * Returns 0; use Kafka tooling/metrics for lag/size insights.
+     * Monitoring lag requires external tools or Admin API checks not implemented here.
      */
     size(_queue: string): Promise<number>;
     /**
-     * Clear a queue by deleting the topic.
+     * Clears a queue by deleting the topic.
+     *
+     * @param queue - The topic name.
      */
     clear(queue: string): Promise<void>;
     /**
-     * Push multiple jobs.
+     * Pushes multiple jobs to a Kafka topic.
+     *
+     * @param queue - The topic name.
+     * @param jobs - Array of jobs.
      */
     pushMany(queue: string, jobs: SerializedJob[]): Promise<void>;
     /**
-     * Create a topic.
+     * Creates a new Kafka topic.
+     *
+     * @param topic - The topic name.
+     * @param options - Config for partitions/replication.
      */
     createTopic(topic: string, options?: TopicOptions): Promise<void>;
     /**
-     * Delete a topic.
+     * Deletes a Kafka topic.
+     *
+     * @param topic - The topic name.
      */
     deleteTopic(topic: string): Promise<void>;
     /**
-     * Subscribe to a topic (push-based model).
+     * Subscribes to a topic for streaming jobs.
+     *
+     * Starts a Kafka consumer group and processes messages as they arrive.
+     *
+     * @param queue - The topic name.
+     * @param callback - Function to handle the job.
      */
     subscribe(queue: string, callback: (job: SerializedJob) => Promise<void>): Promise<void>;
 }
 
+/**
+ * Configuration options for the MemoryDriver.
+ */
 interface MemoryDriverConfig {
     /**
-     * Maximum number of jobs per queue.
+     * The maximum number of jobs allowed in a single queue.
+     *
      * @default Infinity
      */
     maxSize?: number;
 }
 /**
- * Memory Driver
+ * In-memory queue driver.
  *
- * In-memory driver for development and testing.
- * All data is stored in memory and will be lost when the process restarts.
- *
- * Zero-config: works out of the box.
+ * Stores jobs in a local JavaScript Map. Ideal for development, testing, and simple
+ * use cases where persistence across restarts is not required.
+ * It supports basic delay handling but data is volatile.
  *
+ * @public
  * @example
  * ```typescript
- * const driver = new MemoryDriver({ maxSize: 1000 })
- * await driver.push('default', serializedJob)
- * const job = await driver.pop('default')
+ * const driver = new MemoryDriver({ maxSize: 1000 });
+ * await driver.push('default', job);
  * ```
  */
 declare class MemoryDriver implements QueueDriver {
@@ -1428,37 +2785,69 @@ declare class MemoryDriver implements QueueDriver {
     private maxSize;
     constructor(config?: MemoryDriverConfig);
     /**
-     * Push a job to a queue.
+     * Pushes a job to the in-memory queue.
+     *
+     * @param queue - The queue name.
+     * @param job - The serialized job.
+     * @throws {Error} If the queue has reached `maxSize`.
      */
     push(queue: string, job: SerializedJob): Promise<void>;
     /**
-     * Pop a job from a queue (FIFO).
+     * Pops the next available job from the queue.
+     *
+     * Respects `delaySeconds` by checking the job's `createdAt` timestamp.
+     *
+     * @param queue - The queue name.
+     * @returns The job or `null`.
      */
     pop(queue: string): Promise<SerializedJob | null>;
     /**
-     * Get queue size.
+     * Returns the number of jobs in the queue.
+     *
+     * @param queue - The queue name.
      */
     size(queue: string): Promise<number>;
     /**
-     * Clear a queue.
+     * Clears all jobs from the queue.
+     *
+     * @param queue - The queue name.
      */
     clear(queue: string): Promise<void>;
     /**
-     * Mark a job as permanently failed.
+     * Moves a job to the failed (DLQ) list.
+     *
+     * In MemoryDriver, this simply pushes to a `failed:{queue}` list.
+     *
+     * @param queue - The original queue name.
+     * @param job - The failed job.
      */
     fail(queue: string, job: SerializedJob): Promise<void>;
     /**
-     * Get queue statistics.
+     * Retrieves statistics for the queue.
+     *
+     * Calculates pending, delayed, and failed counts by iterating through the list.
+     *
+     * @param queue - The queue name.
      */
     stats(queue: string): Promise<QueueStats>;
     /**
-     * Push multiple jobs.
+     * Pushes multiple jobs to the queue.
+     *
+     * @param queue - The queue name.
+     * @param jobs - Array of jobs.
      */
     pushMany(queue: string, jobs: SerializedJob[]): Promise<void>;
     /**
-     * Pop multiple jobs.
+     * Pops multiple jobs from the queue.
+     *
+     * @param queue - The queue name.
+     * @param count - Max jobs to pop.
      */
     popMany(queue: string, count: number): Promise<SerializedJob[]>;
+    /**
+     * Lists all active queues in memory.
+     */
+    getQueues(): Promise<string[]>;
 }
 
 /**
@@ -1480,21 +2869,17 @@ interface RabbitMQDriverConfig {
     exchangeType?: 'direct' | 'topic' | 'headers' | 'fanout' | 'match';
 }
 /**
- * RabbitMQ Driver
- *
- * Uses RabbitMQ as the queue backend.
- * Implements FIFO via RabbitMQ Queues.
+ * RabbitMQ (AMQP) queue driver.
  *
- * Requires `amqplib`.
+ * Uses RabbitMQ as the backend. Supports standard AMQP queues, exchanges,
+ * and reliable message acknowledgements.
  *
+ * @public
  * @example
  * ```typescript
- * import amqp from 'amqplib'
- *
- * const connection = await amqp.connect('amqp://localhost')
- * const driver = new RabbitMQDriver({ client: connection })
- *
- * await driver.push('default', serializedJob)
+ * import amqp from 'amqplib';
+ * const conn = await amqp.connect('amqp://localhost');
+ * const driver = new RabbitMQDriver({ client: conn });
  * ```
  */
 declare class RabbitMQDriver implements QueueDriver {
@@ -1512,20 +2897,29 @@ declare class RabbitMQDriver implements QueueDriver {
      */
     getRawConnection(): any;
     /**
-     * Push a job (sendToQueue / publish).
+     * Pushes a job to a RabbitMQ queue or exchange.
+     *
+     * @param queue - The queue name.
+     * @param job - The serialized job.
      */
     push(queue: string, job: SerializedJob): Promise<void>;
     /**
-     * Pop a job (get).
+     * Pops a job from the queue.
+     *
+     * @param queue - The queue name.
      */
     pop(queue: string): Promise<SerializedJob | null>;
     /**
-     * Pop multiple jobs.
-     * Uses channel.get() in a loop (no native batch get in AMQP).
+     * Pops multiple jobs.
+     *
+     * @param queue - The queue name.
+     * @param count - Max jobs.
      */
     popMany(queue: string, count: number): Promise<SerializedJob[]>;
     /**
-     * Acknowledge a message.
+     * Acknowledges a message.
+     *
+     * @param messageId - The message object (RabbitMQ requires object reference).
      */
     acknowledge(messageId: string): Promise<void>;
     /**
@@ -1537,18 +2931,22 @@ declare class RabbitMQDriver implements QueueDriver {
      */
     reject(message: any, requeue?: boolean): Promise<void>;
     /**
-     * Subscribe to a queue.
+     * Subscribes to a queue.
      */
     subscribe(queue: string, callback: (job: SerializedJob) => Promise<void>, options?: {
         autoAck?: boolean;
         prefetch?: number;
     }): Promise<void>;
     /**
-     * Get queue size.
+     * Returns the number of messages in the queue.
+     *
+     * @param queue - The queue name.
      */
     size(queue: string): Promise<number>;
     /**
-     * Clear a queue.
+     * Purges the queue.
+     *
+     * @param queue - The queue name.
      */
     clear(queue: string): Promise<void>;
 }
@@ -1581,6 +2979,18 @@ interface RedisClient {
     eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<any>;
     [key: string]: any;
 }
+/**
+ * Extended Redis client with custom commands.
+ */
+interface CustomRedisClient extends RedisClient {
+    pushGroupJob(waitList: string, activeSet: string, pendingList: string, groupId: string, payload: string): Promise<number>;
+    completeGroupJob(waitList: string, activeSet: string, pendingList: string, groupId: string): Promise<number>;
+    popMany(queue: string, prefix: string, count: number, now: string): Promise<string[]>;
+}
+/**
+ * Extended Redis client with custom group commands (Legacy name).
+ */
+type GroupRedisClient = CustomRedisClient;
 /**
  * Redis driver configuration.
  */
@@ -1595,22 +3005,18 @@ interface RedisDriverConfig {
     prefix?: string;
 }
 /**
- * Redis Driver
+ * High-performance Redis queue driver.
  *
- * Uses Redis as the queue backend.
- * Implements FIFO via Redis Lists (LPUSH/RPOP).
- *
- * Requires `ioredis` or `redis`.
+ * Implements FIFO queues using Redis Lists, reliable priority support, delayed jobs via Sorted Sets,
+ * and rate limiting. Uses Lua scripts for atomic operations and advanced features like
+ * group-based sequential processing.
  *
+ * @public
  * @example
  * ```typescript
- * import Redis from 'ioredis'
- *
- * const redis = new Redis('redis://localhost:6379')
- * const redis = new Redis('ioredis://localhost:6379')
- * const driver = new RedisDriver({ client: redis })
- *
- * await driver.push('default', serializedJob)
+ * import Redis from 'ioredis';
+ * const redis = new Redis();
+ * const driver = new RedisDriver({ client: redis });
  * ```
  */
 declare class RedisDriver implements QueueDriver {
@@ -1625,16 +3031,32 @@ declare class RedisDriver implements QueueDriver {
      */
     private getKey;
     /**
-     * Push a job (LPUSH).
+     * Pushes a job to Redis.
+     *
+     * Handles regular jobs (LPUSH), delayed jobs (ZADD), and grouped jobs (custom Lua logic).
+     *
+     * @param queue - The queue name.
+     * @param job - The serialized job.
+     * @param options - Push options.
      */
     push(queue: string, job: SerializedJob, options?: JobPushOptions): Promise<void>;
     /**
-     * Complete a job (handle Group FIFO).
+     * Completes a job.
+     *
+     * Crucial for Group FIFO logic to unlock the next job in the group.
+     *
+     * @param queue - The queue name.
+     * @param job - The job to complete.
      */
     complete(queue: string, job: SerializedJob): Promise<void>;
     /**
-     * Pop a job from a queue (non-blocking).
-     * Optimized with Lua script for atomic priority polling.
+     * Pops a job from the queue.
+     *
+     * Checks priorities in order (critical -> high -> default -> low).
+     * Also checks for due delayed jobs and moves them to the active list.
+     *
+     * @param queue - The queue name.
+     * @returns The job or `null`.
      */
     pop(queue: string): Promise<SerializedJob | null>;
     /**
@@ -1642,8 +3064,12 @@ declare class RedisDriver implements QueueDriver {
      */
     private popManualFallback;
     /**
-     * Pop a job from the queue (blocking).
-     * Uses BRPOP for efficiency. Supports multiple queues and priorities.
+     * Pops a job using blocking Redis commands (BRPOP).
+     *
+     * Efficiently waits for a job to arrive without polling.
+     *
+     * @param queues - The queues to listen to.
+     * @param timeout - Timeout in seconds.
      */
     popBlocking(queues: string | string[], timeout: number): Promise<SerializedJob | null>;
     /**
@@ -1651,60 +3077,101 @@ declare class RedisDriver implements QueueDriver {
      */
     private parsePayload;
     /**
-     * Get queue size.
+     * Returns the length of the queue (Redis List length).
+     *
+     * @param queue - The queue name.
      */
     size(queue: string): Promise<number>;
     /**
-     * Mark a job as permanently failed (DLQ).
+     * Marks a job as permanently failed by moving it to a DLQ list.
+     *
+     * @param queue - The queue name.
+     * @param job - The failed job.
      */
     fail(queue: string, job: SerializedJob): Promise<void>;
     /**
-     * Clear a queue.
+     * Clears the queue and its associated delayed/active sets.
+     *
+     * @param queue - The queue name.
      */
     clear(queue: string): Promise<void>;
     /**
-     * Get queue statistics.
-     * Optimized with Redis Pipeline to fetch all priorities and DLQ stats in one trip.
+     * Retrieves full stats for the queue using Redis Pipelining.
+     *
+     * Aggregates counts from all priority lists and the DLQ.
+     *
+     * @param queue - The queue name.
      */
     stats(queue: string): Promise<QueueStats>;
     /**
-     * Push multiple jobs.
+     * Pushes multiple jobs to the queue.
+     *
+     * Uses pipeline for batch efficiency. Falls back to individual pushes if complex logic (groups/priority) is involved.
+     *
+     * @param queue - The queue name.
+     * @param jobs - Array of jobs.
      */
     pushMany(queue: string, jobs: SerializedJob[]): Promise<void>;
     /**
-     * Pop multiple jobs.
-     * Atomic operation across multiple priority levels.
+     * Pops multiple jobs from the queue.
+     *
+     * Uses a Lua script for atomic retrieval across priorities.
+     *
+     * @param queue - The queue name.
+     * @param count - Max jobs to pop.
      */
     popMany(queue: string, count: number): Promise<SerializedJob[]>;
     /**
-     * Report worker heartbeat for monitoring.
+     * Reports a worker heartbeat.
+     *
+     * Stores worker metadata in a key with an expiration (TTL).
      */
     reportHeartbeat(workerInfo: any, prefix?: string): Promise<void>;
     /**
-     * Publish a log message for monitoring.
+     * Publishes monitoring logs.
+     *
+     * Uses Redis Pub/Sub for real-time logs and a capped List for history.
      */
     publishLog(logPayload: any, prefix?: string): Promise<void>;
     /**
-     * Check if a queue is rate limited.
-     * Uses a fixed window counter.
+     * Checks the rate limit for a queue.
+     *
+     * Uses a simple Fixed Window counter (INCR + EXPIRE).
+     *
+     * @param queue - The queue name.
+     * @param config - Rate limit rules.
      */
     checkRateLimit(queue: string, config: {
         max: number;
         duration: number;
     }): Promise<boolean>;
     /**
-     * Get failed jobs from DLQ.
+     * Retrieves failed jobs from the DLQ.
+     *
+     * @param queue - The queue name.
+     * @param start - Start index.
+     * @param end - End index.
      */
     getFailed(queue: string, start?: number, end?: number): Promise<SerializedJob[]>;
     /**
-     * Retry failed jobs from DLQ.
-     * Moves jobs from failed list back to the main queue.
+     * Retries failed jobs.
+     *
+     * Pops from DLQ and pushes back to the active queue (RPOPLPUSH equivalent logic).
+     *
+     * @param queue - The queue name.
+     * @param count - Jobs to retry.
      */
     retryFailed(queue: string, count?: number): Promise<number>;
     /**
-     * Clear failed jobs from DLQ.
+     * Clears the Dead Letter Queue.
+     *
+     * @param queue - The queue name.
      */
     clearFailed(queue: string): Promise<void>;
+    /**
+     * Retrieves all discovered queue names from Redis.
+     */
+    getQueues(): Promise<string[]>;
 }
 
 /**
@@ -1738,27 +3205,17 @@ interface SQSDriverConfig {
     waitTimeSeconds?: number;
 }
 /**
- * SQS Driver
- *
- * Uses AWS SQS as the queue backend.
- * Supports standard/FIFO queues, long polling, DLQ setups, etc.
+ * Amazon SQS queue driver.
  *
- * Requires `@aws-sdk/client-sqs`.
+ * Wraps the AWS SDK for SQS. Supports standard and FIFO queues, long polling,
+ * and visibility timeouts.
  *
+ * @public
  * @example
  * ```typescript
- * import { SQSClient } from '@aws-sdk/client-sqs'
- *
- * const sqs = new SQSClient({
- *   region: 'us-east-1',
- *   credentials: {
- *     accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
- *     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
- *   }
- * })
- *
- * const driver = new SQSDriver({ client: sqs })
- * await driver.push('default', serializedJob)
+ * import { SQSClient } from '@aws-sdk/client-sqs';
+ * const sqs = new SQSClient({ region: 'us-east-1' });
+ * const driver = new SQSDriver({ client: sqs });
  * ```
  */
 declare class SQSDriver implements QueueDriver {
@@ -1773,98 +3230,371 @@ declare class SQSDriver implements QueueDriver {
      */
     private getQueueUrl;
     /**
-     * Push a job to SQS.
+     * Pushes a job to SQS.
+     *
+     * @param queue - The queue name (or URL).
+     * @param job - The serialized job.
      */
     push(queue: string, job: SerializedJob): Promise<void>;
     /**
-     * Pop a job (long polling).
+     * Pops a job from SQS (using long polling).
+     *
+     * @param queue - The queue name (or URL).
      */
     pop(queue: string): Promise<SerializedJob | null>;
     /**
-     * Pop multiple jobs.
-     * Leverages SQS MaxNumberOfMessages (up to 10).
+     * Pops multiple jobs (up to 10).
+     *
+     * @param queue - The queue name.
+     * @param count - Max jobs (capped at 10 by SQS).
      */
     popMany(queue: string, count: number): Promise<SerializedJob[]>;
     /**
-     * Get queue size (approximate).
+     * Returns the approximate number of messages in the queue.
+     *
+     * @param queue - The queue name.
      */
     size(queue: string): Promise<number>;
     /**
-     * Clear a queue by receiving and deleting messages.
+     * Clears the queue by continuously receiving and deleting messages.
+     *
+     * SQS does not have a "purge" command in the client data plane easily accessible here,
+     * so we drain the queue.
      *
-     * Note: SQS does not provide a direct "purge" API via this wrapper. This method will
-     * keep receiving and deleting messages until the queue is empty.
+     * @param queue - The queue name.
      */
     clear(queue: string): Promise<void>;
     /**
-     * Push multiple jobs.
+     * Pushes multiple jobs using SQS batch API.
+     *
+     * @param queue - The queue name.
+     * @param jobs - Array of jobs.
      */
     pushMany(queue: string, jobs: SerializedJob[]): Promise<void>;
     /**
-     * Acknowledge is not supported via messageId.
+     * Throws error as SQS requires ReceiptHandle, not just MessageId.
      */
     acknowledge(_messageId: string): Promise<void>;
     /**
-     * Delete a message (acknowledge processing completion).
+     * Deletes a message using its ReceiptHandle (ACK).
+     *
+     * @param queue - The queue name.
+     * @param receiptHandle - The SQS receipt handle.
      */
     deleteMessage(queue: string, receiptHandle: string): Promise<void>;
 }
 
 /**
- * Options for configuring OrbitStream (Queue Orbit).
+ * Configuration options for distributed locks.
+ *
+ * Defines the time-to-live (TTL), retry strategy, and automatic renewal behavior for a lock.
+ *
+ * @public
+ * @since 3.1.0
+ * @example
+ * ```typescript
+ * const options: LockOptions = {
+ *   ttl: 60000,           // Lock held for 60 seconds
+ *   retryCount: 3,        // Retry 3 times on failure
+ *   retryDelay: 100,      // Wait 100ms between retries
+ *   refreshInterval: 20000 // Auto-renew every 20 seconds
+ * };
+ * ```
+ */
+interface LockOptions {
+    /**
+     * Time-to-live for the lock in milliseconds.
+     *
+     * The lock will automatically expire if the holder does not release or renew it
+     * before this duration elapses.
+     */
+    ttl: number;
+    /**
+     * Number of retry attempts if lock acquisition fails.
+     *
+     * Set to 0 to disable retries.
+     */
+    retryCount: number;
+    /**
+     * Delay between retry attempts in milliseconds.
+     */
+    retryDelay: number;
+    /**
+     * Interval for automatic lock renewal in milliseconds.
+     *
+     * If set, the lock will automatically extend its TTL every `refreshInterval`.
+     * Recommended value is 1/3 of the `ttl`.
+     *
+     * @optional
+     */
+    refreshInterval?: number;
+}
+/**
+ * Distributed lock implementation based on Redis (Redlock style).
+ *
+ * Provides mutual exclusion in a distributed environment, ensuring only one node
+ * holds a specific lock at a time. Supports automatic renewal, retry mechanisms,
+ * and safe release (only the holder can release).
+ *
+ * @public
+ * @since 3.1.0
+ * @example
+ * ```typescript
+ * const lock = new DistributedLock(redisClient);
+ *
+ * const acquired = await lock.acquire('my-resource', {
+ *   ttl: 60000,
+ *   retryCount: 3,
+ *   retryDelay: 100,
+ *   refreshInterval: 20000
+ * });
+ *
+ * if (acquired) {
+ *   try {
+ *     // Perform exclusive operation
+ *   } finally {
+ *     await lock.release('my-resource');
+ *   }
+ * }
+ * ```
+ */
+declare class DistributedLock {
+    private client;
+    /**
+     * Unique identifier for this lock instance.
+     * Used to ensure only the owner can release the lock.
+     */
+    private lockId;
+    /**
+     * Timer for automatic renewal.
+     */
+    private refreshTimer;
+    /**
+     * The key of the currently held lock.
+     */
+    private currentLockKey;
+    /**
+     * Creates a DistributedLock instance.
+     *
+     * @param client - Redis client instance. Must support SET, DEL, and EVAL commands.
+     */
+    constructor(client: GroupRedisClient);
+    /**
+     * Attempts to acquire a distributed lock for the specified key.
+     *
+     * Uses Redis `SET key value EX ttl NX` for atomic acquisition.
+     * If the lock is held by another node, it retries according to `retryCount`.
+     * Upon success, if `refreshInterval` is set, automatic renewal starts.
+     *
+     * @param key - The lock key. Use a meaningful resource identifier.
+     * @param options - Configuration options for the lock.
+     * @returns `true` if the lock was acquired, `false` otherwise.
+     *
+     * @throws {Error} If the Redis client does not support the SET command.
+     *
+     * @example
+     * ```typescript
+     * const acquired = await lock.acquire('schedule:job-123', {
+     *   ttl: 30000,
+     *   retryCount: 5,
+     *   retryDelay: 200
+     * });
+     *
+     * if (!acquired) {
+     *   console.log('Resource is currently locked by another node');
+     * }
+     * ```
+     */
+    acquire(key: string, options: LockOptions): Promise<boolean>;
+    /**
+     * Releases the lock for the specified key.
+     *
+     * Uses a Lua script to ensure atomicity: the lock is deleted ONLY if the value matches
+     * this instance's `lockId`. This prevents deleting locks held by others.
+     * Stops the auto-renewal timer upon success.
+     *
+     * @param key - The lock key to release.
+     *
+     * @throws {Error} If the Redis client does not support the EVAL command.
+     *
+     * @example
+     * ```typescript
+     * await lock.release('schedule:job-123');
+     * ```
+     */
+    release(key: string): Promise<void>;
+    /**
+     * Starts the automatic renewal mechanism.
+     *
+     * Periodically extends the lock's TTL to prevent expiration during long-running tasks.
+     * Uses a Lua script to ensure only owned locks are renewed.
+     *
+     * @param key - The lock key.
+     * @param options - Lock options containing `refreshInterval`.
+     */
+    private startRefresh;
+    /**
+     * Stops the automatic renewal timer.
+     */
+    private stopRefresh;
+    /**
+     * Helper for delay.
+     *
+     * @param ms - Milliseconds to sleep.
+     */
+    private sleep;
+    /**
+     * Checks if the specified lock is currently held by this instance.
+     *
+     * @param key - The lock key.
+     * @returns `true` if held, `false` otherwise.
+     *
+     * @example
+     * ```typescript
+     * if (lock.isHeld('schedule:job-123')) {
+     *   console.log('Lock is active');
+     * }
+     * ```
+     */
+    isHeld(key: string): boolean;
+}
+
+/**
+ * Configuration options for the OrbitStream extension.
+ *
+ * Extends the standard `QueueConfig` with specific options for integration into
+ * the Gravito lifecycle, such as auto-starting workers in development environments.
+ *
  * @public
+ * @example
+ * ```typescript
+ * const options: OrbitStreamOptions = {
+ *   default: 'redis',
+ *   autoStartWorker: true
+ * };
+ * ```
  */
 interface OrbitStreamOptions extends QueueConfig {
     /**
-     * Whether to automatically start an embedded worker in development mode.
-     * Useful for simple local testing without running a separate worker process.
+     * Automatically start an embedded worker process.
+     *
+     * If set to `true`, a background worker will be spawned within the main process.
+     * This is recommended for development or simple deployments but should be
+     * avoided in high-scale production to keep web servers stateless.
      */
     autoStartWorker?: boolean;
     /**
-     * Configuration for the embedded worker/consumer.
+     * Configuration options for the embedded worker.
+     *
+     * Only used if `autoStartWorker` is true. Defines concurrency, polling intervals, etc.
      */
     workerOptions?: ConsumerOptions;
+    /**
+     * Configuration for the Stream Monitoring Dashboard API.
+     *
+     * If enabled, registers API routes for monitoring queue health and job history.
+     *
+     * @default false
+     */
+    dashboard?: boolean | {
+        /**
+         * Base path for the dashboard API routes.
+         * @default '/_flux'
+         */
+        path?: string;
+    };
 }
 /**
- * OrbitStream provides a powerful, multi-driver queue system for Gravito.
- * It integrates with various backends (Redis, Database, SQS, RabbitMQ)
- * and supports job serialization, delayed jobs, and FIFO processing.
+ * The Queue Orbit (Plugin) for Gravito Framework.
+ *
+ * This class acts as the integration layer between the `@gravito/stream` package
+ * and the Gravito core system (`PlanetCore`). It registers the `QueueManager`
+ * service, injects it into the request context, and manages the lifecycle of
+ * embedded workers.
  *
+ * @public
  * @example
  * ```typescript
- * const stream = new OrbitStream({
+ * const stream = OrbitStream.configure({
  *   default: 'redis',
  *   connections: {
- *     redis: { driver: 'redis', host: 'localhost' }
+ *     redis: { driver: 'redis', client: redis }
  *   }
  * });
- * core.addOrbit(stream);
+ *
+ * await PlanetCore.boot({ orbits: [stream] });
  * ```
- * @public
  */
 declare class OrbitStream implements GravitoOrbit {
     private options;
     private queueManager?;
     private consumer?;
+    private core?;
     constructor(options?: OrbitStreamOptions);
     /**
-     * Static configuration helper.
+     * Factory method for creating and configuring an OrbitStream instance.
+     *
+     * Provides a fluent way to instantiate the orbit during application bootstrap.
+     *
+     * @param options - Configuration options.
+     * @returns A new OrbitStream instance.
+     *
+     * @example
+     * ```typescript
+     * const orbit = OrbitStream.configure({ default: 'memory' });
+     * ```
      */
     static configure(options: OrbitStreamOptions): OrbitStream;
     /**
-     * Install into PlanetCore.
+     * Installs the Queue system into the Gravito PlanetCore.
+     *
+     * This lifecycle method:
+     * 1. Initializes the `QueueManager`.
+     * 2. Registers the `queue` service in the dependency injection container.
+     * 3. Sets up a global middleware to inject `QueueManager` into the request context (`c.get('queue')`).
+     * 4. Automatically detects and registers database connections if available in the context.
+     * 5. Starts the embedded worker if configured.
+     *
+     * @param core - The PlanetCore instance.
      */
     install(core: PlanetCore): void;
     /**
-     * Start embedded worker.
+     * Starts the embedded worker process.
+     *
+     * Launches a `Consumer` instance to process jobs in the background.
+     * Throws an error if `QueueManager` is not initialized or if a worker is already running.
+     *
+     * @param options - Consumer configuration options.
+     * @throws {Error} If QueueManager is missing or worker is already active.
+     *
+     * @example
+     * ```typescript
+     * orbit.startWorker({ queues: ['default'] });
+     * ```
      */
     startWorker(options: ConsumerOptions): void;
     /**
-     * Stop embedded worker.
+     * Stops the embedded worker process.
+     *
+     * Gracefully shuts down the consumer, waiting for active jobs to complete.
+     *
+     * @returns A promise that resolves when the worker has stopped.
+     *
+     * @example
+     * ```typescript
+     * await orbit.stopWorker();
+     * ```
      */
     stopWorker(): Promise<void>;
     /**
-     * Get QueueManager instance.
+     * Retrieves the underlying QueueManager instance.
+     *
+     * @returns The active QueueManager, or undefined if not installed.
+     *
+     * @example
+     * ```typescript
+     * const manager = orbit.getQueueManager();
+     * ```
      */
     getQueueManager(): QueueManager | undefined;
 }
@@ -1879,7 +3609,20 @@ declare module '@gravito/core' {
 
 /**
  * Buffered Persistence Wrapper.
- * Wraps any PersistenceAdapter to add buffering and batch writing capabilities.
+ *
+ * Decorates any `PersistenceAdapter` to add write buffering. Instead of writing
+ * to the database immediately for every event, it collects jobs and logs in memory
+ * and flushes them in batches. This significantly reduces database I/O for high-throughput queues.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const mysqlAdapter = new MySQLPersistence(db);
+ * const bufferedAdapter = new BufferedPersistence(mysqlAdapter, {
+ *   maxBufferSize: 100,
+ *   flushInterval: 500
+ * });
+ * ```
  */
 declare class BufferedPersistence implements PersistenceAdapter {
     private adapter;
@@ -1892,8 +3635,21 @@ declare class BufferedPersistence implements PersistenceAdapter {
         maxBufferSize?: number;
         flushInterval?: number;
     });
+    /**
+     * Buffers a job archive request.
+     *
+     * @param queue - The queue name.
+     * @param job - The serialized job.
+     * @param status - The final job status.
+     */
     archive(queue: string, job: SerializedJob, status: 'completed' | 'failed' | 'waiting' | string): Promise<void>;
+    /**
+     * Delegates find to the underlying adapter (no buffering for reads).
+     */
     find(queue: string, id: string): Promise<SerializedJob | null>;
+    /**
+     * Delegates list to the underlying adapter (no buffering for reads).
+     */
     list(queue: string, options?: {
         limit?: number;
         offset?: number;
@@ -1902,19 +3658,38 @@ declare class BufferedPersistence implements PersistenceAdapter {
         startTime?: Date;
         endTime?: Date;
     }): Promise<SerializedJob[]>;
+    /**
+     * Archives multiple jobs directly (bypassing buffer, or flushing first).
+     *
+     * Actually, for consistency, this might just pass through.
+     */
     archiveMany(jobs: Array<{
         queue: string;
         job: SerializedJob;
         status: 'completed' | 'failed' | 'waiting' | string;
     }>): Promise<void>;
+    /**
+     * Delegates cleanup to the underlying adapter.
+     */
     cleanup(days: number): Promise<number>;
+    /**
+     * Flushes all buffered data to the underlying adapter.
+     *
+     * Uses `archiveMany` and `archiveLogMany` if supported by the adapter for batch efficiency.
+     */
     flush(): Promise<void>;
+    /**
+     * Delegates count to the underlying adapter.
+     */
     count(queue: string, options?: {
         status?: 'completed' | 'failed' | 'waiting' | string;
         jobId?: string;
         startTime?: Date;
         endTime?: Date;
     }): Promise<number>;
+    /**
+     * Buffers a log message.
+     */
     archiveLog(log: {
         level: string;
         message: string;
@@ -1922,6 +3697,9 @@ declare class BufferedPersistence implements PersistenceAdapter {
         queue?: string;
         timestamp: Date;
     }): Promise<void>;
+    /**
+     * Archives multiple logs directly.
+     */
     archiveLogMany(logs: Array<{
         level: string;
         message: string;
@@ -1929,6 +3707,9 @@ declare class BufferedPersistence implements PersistenceAdapter {
         queue?: string;
         timestamp: Date;
     }>): Promise<void>;
+    /**
+     * Delegates listLogs to the underlying adapter.
+     */
     listLogs(options?: {
         limit?: number;
         offset?: number;
@@ -1939,6 +3720,9 @@ declare class BufferedPersistence implements PersistenceAdapter {
         startTime?: Date;
         endTime?: Date;
     }): Promise<any[]>;
+    /**
+     * Delegates countLogs to the underlying adapter.
+     */
     countLogs(options?: {
         level?: string;
         workerId?: string;
@@ -1947,12 +3731,23 @@ declare class BufferedPersistence implements PersistenceAdapter {
         startTime?: Date;
         endTime?: Date;
     }): Promise<number>;
+    /**
+     * Ensures the auto-flush timer is running.
+     */
     private ensureFlushTimer;
 }
 
 /**
  * MySQL Persistence Adapter.
- * Archives jobs into a MySQL table for long-term auditing.
+ *
+ * Implements the `PersistenceAdapter` interface for MySQL databases.
+ * Stores job history and logs in relational tables for long-term retention and auditing.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const persistence = new MySQLPersistence(dbConnection);
+ * ```
  */
 declare class MySQLPersistence implements PersistenceAdapter {
     private db;
@@ -1968,13 +3763,25 @@ declare class MySQLPersistence implements PersistenceAdapter {
         maxBufferSize?: number;
         flushInterval?: number;
     });
+    /**
+     * Archives a single job.
+     */
     archive(queue: string, job: SerializedJob, status: 'completed' | 'failed' | 'waiting' | string): Promise<void>;
+    /**
+     * Archives multiple jobs in a batch.
+     */
     archiveMany(jobs: Array<{
         queue: string;
         job: SerializedJob;
         status: 'completed' | 'failed' | 'waiting' | string;
     }>): Promise<void>;
+    /**
+     * No-op. Use BufferedPersistence if flushing is needed.
+     */
     flush(): Promise<void>;
+    /**
+     * Finds an archived job by ID.
+     */
     find(queue: string, id: string): Promise<SerializedJob | null>;
     /**
      * List jobs from the archive.
@@ -1989,6 +3796,9 @@ declare class MySQLPersistence implements PersistenceAdapter {
     }): Promise<SerializedJob[]>;
     /**
      * Search jobs from the archive.
+     *
+     * @param query - Search string (matches ID, payload, or error).
+     * @param options - Filter options.
      */
     search(query: string, options?: {
         limit?: number;
@@ -1996,7 +3806,7 @@ declare class MySQLPersistence implements PersistenceAdapter {
         queue?: string;
     }): Promise<SerializedJob[]>;
     /**
-     * Archive a system log message (buffered).
+     * Archive a system log message.
      */
     archiveLog(log: {
         level: string;
@@ -2006,7 +3816,7 @@ declare class MySQLPersistence implements PersistenceAdapter {
         timestamp: Date;
     }): Promise<void>;
     /**
-     * Archive multiple log messages (direct batch write).
+     * Archive multiple log messages.
      */
     archiveLogMany(logs: Array<{
         level: string;
@@ -2053,7 +3863,7 @@ declare class MySQLPersistence implements PersistenceAdapter {
         endTime?: Date;
     }): Promise<number>;
     /**
-     * Help script to create the necessary table.
+     * Helper to create necessary tables if they don't exist.
      */
     setupTable(): Promise<void>;
     private setupJobsTable;
@@ -2062,7 +3872,15 @@ declare class MySQLPersistence implements PersistenceAdapter {
 
 /**
  * SQLite Persistence Adapter.
+ *
  * Archives jobs into a local SQLite database for zero-config persistence.
+ * Uses transactions to optimize write performance for batches.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const persistence = new SQLitePersistence(db);
+ * ```
  */
 declare class SQLitePersistence implements PersistenceAdapter {
     private db;
@@ -2078,13 +3896,27 @@ declare class SQLitePersistence implements PersistenceAdapter {
         maxBufferSize?: number;
         flushInterval?: number;
     });
+    /**
+     * Archives a single job.
+     */
     archive(queue: string, job: SerializedJob, status: 'completed' | 'failed' | 'waiting' | string): Promise<void>;
+    /**
+     * Archives multiple jobs in a batch.
+     *
+     * Optimized for SQLite by wrapping chunks in transactions.
+     */
     archiveMany(jobs: Array<{
         queue: string;
         job: SerializedJob;
         status: 'completed' | 'failed' | 'waiting' | string;
     }>): Promise<void>;
+    /**
+     * No-op. Use BufferedPersistence if flushing is needed.
+     */
     flush(): Promise<void>;
+    /**
+     * Finds an archived job by ID.
+     */
     find(queue: string, id: string): Promise<SerializedJob | null>;
     /**
      * List jobs from the archive.
@@ -2092,7 +3924,7 @@ declare class SQLitePersistence implements PersistenceAdapter {
     list(queue: string, options?: {
         limit?: number;
         offset?: number;
-        status?: 'completed' | 'failed' | 'waiting' | string;
+        status?: 'completed' | 'failed' | 'waiting' | string | string[];
         jobId?: string;
         startTime?: Date;
         endTime?: Date;
@@ -2157,7 +3989,7 @@ declare class SQLitePersistence implements PersistenceAdapter {
      * Count jobs in the archive.
      */
     count(queue: string, options?: {
-        status?: 'completed' | 'failed' | 'waiting' | string;
+        status?: 'completed' | 'failed' | 'waiting' | string | string[];
         jobId?: string;
         startTime?: Date;
         endTime?: Date;
@@ -2171,72 +4003,385 @@ declare class SQLitePersistence implements PersistenceAdapter {
 }
 
 /**
- * Class name serializer (Laravel-style).
+ * Retry strategy for events.
+ *
+ * - 'bull': Use Bull Queue's built-in retry mechanism
+ * - 'core': Use EventPriorityQueue's retry logic (not implemented in Stream backend)
+ * - 'hybrid': Bull retries + Core DLQ fallback (future phase)
+ */
+type RetryStrategy = 'bull' | 'core' | 'hybrid';
+/**
+ * Configuration for StreamEventBackend.
+ */
+interface StreamEventBackendConfig {
+    /**
+     * Retry strategy to use.
+     * @default 'bull'
+     */
+    retryStrategy?: RetryStrategy;
+    /**
+     * Whether to integrate with CircuitBreaker.
+     * @default false
+     */
+    circuitBreakerIntegration?: boolean;
+    /**
+     * Optional DLQ (Dead Letter Queue) handler for failed events.
+     */
+    dlqHandler?: {
+        handle(event: EventTask, error: Error, attempt: number): Promise<void>;
+    };
+    /**
+     * CircuitBreaker getter (injected from core)
+     */
+    getCircuitBreaker?: (hook: string) => any;
+}
+/**
+ * Event backend implementation using Gravito Stream (Bull Queue).
+ *
+ * Provides persistent, distributed event processing with:
+ * - Bull Queue persistence (Redis-backed)
+ * - Configurable retry strategies
+ * - Optional CircuitBreaker integration
+ * - DLQ support for failed events
+ *
+ * @example
+ * ```typescript
+ * const queueManager = new QueueManager({
+ *   default: 'bullmq',
+ *   connections: {
+ *     bullmq: {
+ *       driver: 'bullmq',
+ *       queue: new Queue('gravito-events', { connection: redis })
+ *     }
+ *   }
+ * })
+ *
+ * const backend = new StreamEventBackend(queueManager, {
+ *   retryStrategy: 'bull',
+ *   circuitBreakerIntegration: true
+ * })
+ * ```
+ */
+declare class StreamEventBackend implements EventBackend {
+    private queueManager;
+    private config;
+    constructor(queueManager: QueueManager, config?: StreamEventBackendConfig);
+    /**
+     * Build Job Push Options from EventOptions.
+     *
+     * Maps EventOptions to Bull Queue JobPushOptions with retry strategy applied.
+     */
+    private buildJobOptions;
+    /**
+     * Enqueue an event task to the stream queue.
+     *
+     * Applies retry strategy and CircuitBreaker checks based on configuration.
+     * Supports DLQ routing for failed events.
+     */
+    enqueue(task: EventTask): Promise<void>;
+    /**
+     * Apply retry strategy to the job based on configuration.
+     */
+    private applyRetryStrategy;
+    /**
+     * Handle job failure and route to DLQ if configured.
+     *
+     * Called when a job exhausts all retry attempts.
+     */
+    handleJobFailure(task: EventTask, error: Error, attempt: number): Promise<void>;
+    /**
+     * Record a job failure for CircuitBreaker state management.
+     *
+     * Called when a job fails, regardless of retry status.
+     */
+    recordJobFailure(task: EventTask, error: Error): void;
+    /**
+     * Record a job success for CircuitBreaker state management.
+     *
+     * Called when a job completes successfully.
+     */
+    recordJobSuccess(task: EventTask): void;
+    /**
+     * Get the retry strategy configuration.
+     */
+    getRetryStrategy(): RetryStrategy;
+    /**
+     * Check if CircuitBreaker integration is enabled.
+     */
+    isCircuitBreakerEnabled(): boolean;
+    /**
+     * Get the DLQ handler, if configured.
+     */
+    getDLQHandler(): StreamEventBackendConfig['dlqHandler'] | undefined;
+}
+
+/**
+ * SystemEventJob - Internal job for processing Gravito async hooks.
+ *
+ * @internal
+ */
+declare class SystemEventJob extends Job {
+    readonly hook: string;
+    readonly args: unknown;
+    readonly options: Record<string, any>;
+    /**
+     * Optional failure callback for DLQ handling.
+     */
+    private onFailedCallback?;
+    constructor(hook: string, args: unknown, options?: Record<string, any>);
+    /**
+     * Set failure callback for DLQ handling.
+     *
+     * @param callback - Called when job fails permanently
+     * @returns Self for chaining
+     */
+    onFailed(callback: (error: Error, attempt: number) => Promise<void>): this;
+    /**
+     * Execute the hook listeners in the worker process.
+     */
+    handle(): Promise<void>;
+    /**
+     * Called when job fails permanently after all retries.
+     *
+     * This method is invoked by the worker when job exhausts all retry attempts.
+     */
+    failed(error: Error, attempt?: number): Promise<void>;
+}
+
+/**
+ * Class Name Serializer (Laravel-style).
  *
- * Stores the class name and properties, then recreates an instance at runtime.
- * This is the recommended serializer because it can restore class instances correctly.
+ * Serializes jobs by storing their class name along with their properties.
+ * During deserialization, it looks up the registered class constructor and creates a new instance,
+ * populating it with the stored properties.
  *
- * Requirement: Job classes must be dynamically loadable (by class name).
+ * This is the recommended serializer for most use cases as it preserves the behavior (methods)
+ * of the job class.
  *
+ * @public
  * @example
  * ```typescript
- * const serializer = new ClassNameSerializer()
- * const serialized = serializer.serialize(new SendEmail('user@example.com'))
- * // serialized.data contains class name and properties
+ * const serializer = new ClassNameSerializer();
+ * serializer.register(SendEmailJob);
  *
- * const job = serializer.deserialize(serialized)
- * // job is an instance of SendEmail
+ * const serialized = serializer.serialize(new SendEmailJob('foo@bar.com'));
+ * const job = serializer.deserialize(serialized); // instanceof SendEmailJob
  * ```
  */
 declare class ClassNameSerializer implements JobSerializer {
     /**
-     * Job class registry (for resolving classes by name).
+     * Registry of job classes, mapped by class name.
      */
     private jobClasses;
     /**
-     * Register a Job class.
-     * @param jobClass - Job class
+     * Registers a Job class for serialization.
+     *
+     * @param jobClass - The job class constructor.
      */
     register(jobClass: new (...args: unknown[]) => Job): void;
     /**
-     * Register multiple Job classes.
-     * @param jobClasses - Job class array
+     * Registers multiple Job classes at once.
+     *
+     * @param jobClasses - An array of job class constructors.
      */
     registerMany(jobClasses: Array<new (...args: unknown[]) => Job>): void;
     /**
-     * Serialize a Job.
+     * Serializes a Job instance.
+     *
+     * Captures the class name and all enumerable properties.
+     *
+     * @param job - The job to serialize.
      */
     serialize(job: Job): SerializedJob;
     /**
-     * Deserialize a Job.
+     * Deserializes a Job instance.
+     *
+     * Instantiates the class matching `className` and assigns properties.
+     *
+     * @param serialized - The serialized job.
+     * @throws {Error} If the job class is not registered.
      */
     deserialize(serialized: SerializedJob): Job;
 }
 
 /**
- * JSON Serializer
- *
- * Serializes jobs using JSON.
- * Suitable for simple scenarios where you only need to persist plain properties.
+ * JSON Serializer.
  *
- * Limitation: cannot restore class instances, functions, or complex objects.
+ * Serializes jobs to standard JSON. This is the simplest serializer but has limitations:
+ * it cannot restore class instances (methods are lost) or handle complex types like Maps/Sets.
+ * Deserialized jobs will be plain objects that must be manually handled or cast.
  *
+ * @public
  * @example
  * ```typescript
- * const serializer = new JsonSerializer()
- * const serialized = serializer.serialize(job)
- * const job = serializer.deserialize(serialized)
+ * const serializer = new JsonSerializer();
  * ```
  */
 declare class JsonSerializer implements JobSerializer {
     /**
-     * Serialize a job.
+     * Serializes a job to a JSON object.
      */
     serialize(job: Job): SerializedJob;
     /**
-     * Deserialize a job.
+     * Deserializes a JSON object into a basic Job-like object.
+     *
+     * Note: The result is NOT an instance of the original Job class.
      */
     deserialize(serialized: SerializedJob): Job;
 }
 
-export { BufferedPersistence, ClassNameSerializer, Consumer, type ConsumerOptions, DatabaseDriver, type DatabaseDriverConfig, Job, type JobSerializer, JsonSerializer, KafkaDriver, type KafkaDriverConfig, MemoryDriver, MySQLPersistence, OrbitStream, type OrbitStreamOptions, type PersistenceAdapter, type QueueConfig, type QueueConnectionConfig, type QueueDriver, QueueManager, type Queueable, RabbitMQDriver, type RabbitMQDriverConfig, RedisDriver, type RedisDriverConfig, SQLitePersistence, SQSDriver, type SQSDriverConfig, Scheduler, type SerializedJob, type TopicOptions, Worker, type WorkerOptions };
+/**
+ * Worker Pool Implementation.
+ *
+ * Manages a pool of Sandboxed Workers to provide concurrency control,
+ * worker reuse, load balancing, and health monitoring.
+ *
+ * @public
+ */
+
+/**
+ * Configuration options for the Worker Pool.
+ */
+interface WorkerPoolConfig extends SandboxedWorkerConfig {
+    /**
+     * The maximum number of workers allowed in the pool.
+     *
+     * @default 4
+     */
+    poolSize?: number;
+    /**
+     * The minimum number of workers to keep alive.
+     *
+     * The pool will pre-warm and maintain at least this many ready workers.
+     * @default 0
+     */
+    minWorkers?: number;
+    /**
+     * Interval for performing health checks in milliseconds.
+     *
+     * Periodically scans for and removes terminated or unhealthy workers.
+     * @default 30000 (30 seconds)
+     */
+    healthCheckInterval?: number;
+}
+/**
+ * Runtime statistics for the Worker Pool.
+ */
+interface WorkerPoolStats {
+    /** Total number of workers (ready + busy). */
+    total: number;
+    /** Number of idle workers ready for new jobs. */
+    ready: number;
+    /** Number of workers currently executing jobs. */
+    busy: number;
+    /** Number of workers in terminated state awaiting cleanup. */
+    terminated: number;
+    /** Number of jobs waiting in the queue. */
+    pending: number;
+    /** Total number of successfully completed jobs. */
+    completed: number;
+    /** Total number of failed jobs. */
+    failed: number;
+}
+/**
+ * Worker Pool.
+ *
+ * Orchestrates multiple `SandboxedWorker` instances to execute jobs concurrently.
+ *
+ * Key features:
+ * - **Concurrency Control**: Limits the number of simultaneous job executions (`poolSize`).
+ * - **Queueing**: Queues jobs when all workers are busy.
+ * - **Lifecycle Management**: Automatically creates, reuses, and terminates workers.
+ * - **Health Monitoring**: Periodically cleans up dead workers and maintains `minWorkers`.
+ *
+ * @example
+ * ```typescript
+ * const pool = new WorkerPool({
+ *   poolSize: 8,
+ *   minWorkers: 2,
+ *   maxExecutionTime: 30000
+ * });
+ *
+ * await pool.execute(job);
+ * await pool.shutdown();
+ * ```
+ */
+declare class WorkerPool {
+    private workers;
+    private config;
+    private queue;
+    private healthCheckTimer;
+    private stats;
+    /**
+     * Creates a WorkerPool instance.
+     *
+     * @param config - Configuration options for the pool.
+     */
+    constructor(config?: WorkerPoolConfig);
+    /**
+     * Pre-warms the pool by creating the minimum number of workers.
+     */
+    private warmUp;
+    /**
+     * Creates a new SandboxedWorker and adds it to the pool.
+     *
+     * @returns The newly created worker.
+     */
+    private createWorker;
+    /**
+     * Retrieves an available worker from the pool.
+     *
+     * Priorities:
+     * 1. Reuse an existing ready worker.
+     * 2. Create a new worker if the pool is not full.
+     * 3. Return `null` if the pool is saturated.
+     *
+     * @returns An available worker or `null`.
+     */
+    private getAvailableWorker;
+    /**
+     * Executes a job using the worker pool.
+     *
+     * If a worker is available, the job starts immediately.
+     * Otherwise, it is added to the pending queue.
+     *
+     * @param job - The serialized job data.
+     * @throws {Error} If execution fails.
+     */
+    execute(job: SerializedJob): Promise<void>;
+    /**
+     * Processes the next job in the queue if a worker is available.
+     */
+    private processQueue;
+    /**
+     * Starts the periodic health check.
+     */
+    private startHealthCheck;
+    /**
+     * Performs a health check on the pool.
+     *
+     * Removes terminated workers and ensures `minWorkers` are available.
+     */
+    private performHealthCheck;
+    /**
+     * Gets the current statistics of the worker pool.
+     *
+     * @returns Snapshot of pool statistics.
+     */
+    getStats(): WorkerPoolStats;
+    /**
+     * Shuts down the worker pool.
+     *
+     * Terminates all workers and rejects any pending jobs.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Waits for all active and pending jobs to complete.
+     *
+     * @param timeout - Maximum wait time in milliseconds. 0 for infinite.
+     * @throws {Error} If the timeout is reached.
+     */
+    waitForCompletion(timeout?: number): Promise<void>;
+}
+
+export { BatchConsumer, type BatchConsumerOptions, BufferedPersistence, BullMQDriver, type BullMQDriverConfig, ClassNameSerializer, Consumer, type ConsumerOptions, DatabaseDriver, type DatabaseDriverConfig, DistributedLock, GrpcDriver, type GrpcDriverConfig, Job, type JobSerializer, JsonSerializer, KafkaDriver, type KafkaDriverConfig, type LockOptions, MemoryDriver, MySQLPersistence, OrbitStream, type OrbitStreamOptions, type PersistenceAdapter, type QueueConfig, type QueueConnectionConfig, type QueueDriver, QueueManager, type Queueable, RabbitMQDriver, type RabbitMQDriverConfig, RedisDriver, type RedisDriverConfig, type RetryStrategy, SQLitePersistence, SQSDriver, type SQSDriverConfig, SandboxedWorker, type SandboxedWorkerConfig, type ScheduledJobConfig, Scheduler, type SchedulerOptions, type SerializedJob, StreamEventBackend, type StreamEventBackendConfig, SystemEventJob, type TopicOptions, Worker, type WorkerOptions, WorkerPool, type WorkerPoolConfig, type WorkerPoolStats };