@gravito/stream 2.0.1 → 2.0.2

package/dist/index.cjs

@@ -30,6 +30,310 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/drivers/BullMQDriver.ts
+var BullMQDriver_exports = {};
+__export(BullMQDriver_exports, {
+  BullMQDriver: () => BullMQDriver
+});
+var BullMQDriver;
+var init_BullMQDriver = __esm({
+  "src/drivers/BullMQDriver.ts"() {
+    "use strict";
+    BullMQDriver = class {
+      queue;
+      prefix;
+      debug;
+      queueMap = /* @__PURE__ */ new Map();
+      constructor(config) {
+        this.queue = config.queue;
+        this.prefix = config.prefix ?? "gravito:";
+        this.debug = config.debug ?? false;
+        if (!this.queue) {
+          throw new Error("[BullMQDriver] Bull Queue instance is required.");
+        }
+      }
+      /**
+       * Get or create a queue for the given queue name.
+       */
+      getQueue(queueName) {
+        const fullName = `${this.prefix}${queueName}`;
+        if (this.queueMap.has(fullName)) {
+          return this.queueMap.get(fullName);
+        }
+        return this.queue;
+      }
+      /**
+       * Build Job Options from JobPushOptions.
+       */
+      buildJobOptions(options) {
+        const bullOptions = {};
+        if (options?.priority) {
+          if (options.priority === "high" || options.priority === "critical") {
+            bullOptions.priority = 1;
+          } else if (options.priority === "low") {
+            bullOptions.priority = 10;
+          } else if (typeof options.priority === "number") {
+            bullOptions.priority = Math.min(Math.max(options.priority, 1), 10);
+          } else {
+            bullOptions.priority = 5;
+          }
+        }
+        return bullOptions;
+      }
+      /**
+       * Create Bull job data from SerializedJob.
+       */
+      createBullJobData(job) {
+        return {
+          id: job.id,
+          type: job.type,
+          data: job.data,
+          className: job.className,
+          createdAt: job.createdAt,
+          delaySeconds: job.delaySeconds,
+          attempts: job.attempts ?? 0,
+          maxAttempts: job.maxAttempts ?? 3,
+          groupId: job.groupId,
+          retryAfterSeconds: job.retryAfterSeconds,
+          retryMultiplier: job.retryMultiplier,
+          error: job.error,
+          failedAt: job.failedAt,
+          priority: job.priority
+        };
+      }
+      /**
+       * Pushes a job to Bull Queue.
+       */
+      async push(queue, job, options) {
+        try {
+          const q = this.getQueue(queue);
+          const bullJobData = this.createBullJobData(job);
+          const bullOptions = this.buildJobOptions(options);
+          if (job.delaySeconds && job.delaySeconds > 0) {
+            bullOptions.delay = job.delaySeconds * 1e3;
+          }
+          bullOptions.attempts = job.maxAttempts ?? 3;
+          if (job.retryAfterSeconds) {
+            bullOptions.backoff = {
+              type: "exponential",
+              delay: job.retryAfterSeconds * 1e3
+            };
+          }
+          if (options?.groupId) {
+            bullOptions.group = {
+              id: options.groupId
+            };
+          }
+          const namespacedJobName = `${queue}:${job.id}`;
+          await q.add(namespacedJobName, bullJobData, bullOptions);
+          if (this.debug) {
+            console.log(`[BullMQDriver] Pushed job ${job.id} to queue ${queue}`);
+          }
+        } catch (error) {
+          console.error(`[BullMQDriver] Failed to push job to queue ${queue}:`, error);
+          throw error;
+        }
+      }
+      /**
+       * Pops a job from Bull Queue.
+       * Note: Bull Queue typically uses Workers, not manual pop.
+       * This is a fallback implementation.
+       */
+      async pop(queue) {
+        try {
+          this.getQueue(queue);
+          return null;
+        } catch (error) {
+          console.error(`[BullMQDriver] Failed to pop from queue ${queue}:`, error);
+          return null;
+        }
+      }
+      /**
+       * Returns the size of the queue.
+       */
+      async size(queue) {
+        try {
+          const q = this.getQueue(queue);
+          const count = await q.count?.();
+          return count ?? 0;
+        } catch (error) {
+          console.error(`[BullMQDriver] Failed to get queue size for ${queue}:`, error);
+          return 0;
+        }
+      }
+      /**
+       * Clears the queue.
+       */
+      async clear(queue) {
+        try {
+          const q = this.getQueue(queue);
+          if (typeof q.clean === "function") {
+            await q.clean(0);
+          }
+        } catch (error) {
+          console.error(`[BullMQDriver] Failed to clear queue ${queue}:`, error);
+          throw error;
+        }
+      }
+      /**
+       * Marks a job as failed (moves to failed list).
+       */
+      async fail(queue, job) {
+        try {
+          const q = this.getQueue(queue);
+          const bullJob = await q.getJob?.(job.id);
+          if (bullJob) {
+            const error = job.error ?? "Job failed";
+            const failureReasonError = new Error(error);
+            await bullJob.moveToFailed?.(failureReasonError, true);
+          }
+        } catch (error) {
+          console.error(`[BullMQDriver] Failed to mark job as failed:`, error);
+          throw error;
+        }
+      }
+      /**
+       * Returns detailed statistics for the queue.
+       */
+      async stats(queue) {
+        try {
+          const q = this.getQueue(queue);
+          const counts = await q.getJobCounts?.(["active", "completed", "failed", "delayed", "waiting"]);
+          const delayed = await q.getDelayedCount?.();
+          const failed = await q.getFailedCount?.();
+          const active = await q.getActiveCount?.();
+          return {
+            queue,
+            size: counts?.waiting ?? 0,
+            delayed: delayed ?? 0,
+            failed: failed ?? 0,
+            reserved: active ?? 0
+          };
+        } catch (error) {
+          console.error(`[BullMQDriver] Failed to get stats for queue ${queue}:`, error);
+          return {
+            queue,
+            size: 0,
+            delayed: 0,
+            failed: 0
+          };
+        }
+      }
+      /**
+       * Retrieves failed jobs from the Dead Letter Queue.
+       */
+      async getFailed(queue, _start = 0, _end = -1) {
+        try {
+          this.getQueue(queue);
+          return [];
+        } catch (error) {
+          console.error(`[BullMQDriver] Failed to get failed jobs for queue ${queue}:`, error);
+          return [];
+        }
+      }
+      /**
+       * Retries failed jobs.
+       */
+      async retryFailed(queue, _count = 1) {
+        try {
+          this.getQueue(queue);
+          return 0;
+        } catch (error) {
+          console.error(`[BullMQDriver] Failed to retry jobs for queue ${queue}:`, error);
+          return 0;
+        }
+      }
+      /**
+       * Clears the Dead Letter Queue.
+       */
+      async clearFailed(queue) {
+        try {
+          const q = this.getQueue(queue);
+          if (typeof q.clean === "function") {
+            await q.clean(0, void 0, "failed");
+          }
+        } catch (error) {
+          console.error(`[BullMQDriver] Failed to clear failed jobs for queue ${queue}:`, error);
+          throw error;
+        }
+      }
+      /**
+       * Creates a new queue/topic.
+       */
+      async createTopic(_topic, _options) {
+      }
+      /**
+       * Deletes a queue/topic.
+       */
+      async deleteTopic(topic) {
+        try {
+          const q = this.getQueue(topic);
+          await q.close?.();
+        } catch (error) {
+          console.error(`[BullMQDriver] Failed to delete queue ${topic}:`, error);
+          throw error;
+        }
+      }
+      /**
+       * Pushes multiple jobs in batch.
+       */
+      async pushMany(queue, jobs) {
+        try {
+          const q = this.getQueue(queue);
+          const bullJobs = jobs.map((job) => {
+            const bullJobData = this.createBullJobData(job);
+            const namespacedJobName = `${queue}:${job.id}`;
+            return {
+              name: namespacedJobName,
+              data: bullJobData
+            };
+          });
+          for (const bullJob of bullJobs) {
+            await q.add(bullJob.name, bullJob.data);
+          }
+        } catch (error) {
+          console.error(`[BullMQDriver] Failed to push multiple jobs to queue ${queue}:`, error);
+          throw error;
+        }
+      }
+      /**
+       * Pops multiple jobs in batch.
+       */
+      async popMany(_queue, _count) {
+        return [];
+      }
+      /**
+       * Reports worker heartbeat.
+       */
+      async reportHeartbeat(workerInfo, _prefix) {
+        if (this.debug) {
+          console.log(`[BullMQDriver] Worker heartbeat from ${workerInfo.id}`);
+        }
+      }
+      /**
+       * Publishes a log message.
+       */
+      async publishLog(logPayload, _prefix) {
+        if (this.debug) {
+          console.log(`[BullMQDriver] [${logPayload.level}] ${logPayload.message}`);
+        }
+      }
+      /**
+       * Checks rate limit for a queue.
+       */
+      async checkRateLimit(_queue, _config) {
+        return true;
+      }
+      /**
+       * Retrieves all queue names.
+       */
+      async getQueues() {
+        return ["default"];
+      }
+    };
+  }
+});
+
 // src/drivers/DatabaseDriver.ts
 var DatabaseDriver_exports = {};
 __export(DatabaseDriver_exports, {
@@ -52,7 +356,12 @@ var init_DatabaseDriver = __esm({
         }
       }
       /**
-       * 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.
        */
       async push(queue, job) {
         const availableAt = job.delaySeconds ? new Date(Date.now() + job.delaySeconds * 1e3) : /* @__PURE__ */ new Date();
@@ -64,7 +373,13 @@ var init_DatabaseDriver = __esm({
         );
       }
       /**
-       * 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`.
        */
       async pop(queue) {
         const result = await this.dbService.execute(
@@ -131,7 +446,10 @@ var init_DatabaseDriver = __esm({
         return job;
       }
       /**
-       * 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.
        */
       async popMany(queue, count) {
         if (count <= 1) {
@@ -190,7 +508,9 @@ var init_DatabaseDriver = __esm({
         }
       }
       /**
-       * Get queue statistics.
+       * Retrieves queue statistics by querying the table.
+       *
+       * @param queue - The queue name.
        */
       async stats(queue) {
         const failedQueue = `failed:${queue}`;
@@ -224,7 +544,9 @@ var init_DatabaseDriver = __esm({
         }
       }
       /**
-       * Get queue size.
+       * Returns the count of pending jobs.
+       *
+       * @param queue - The queue name.
        */
       async size(queue) {
         const result = await this.dbService.execute(
@@ -238,14 +560,18 @@ var init_DatabaseDriver = __esm({
         return result?.[0]?.count ?? 0;
       }
       /**
-       * Clear a queue.
+       * Clears the queue by deleting all rows for the queue.
+       *
+       * @param queue - The queue name.
        */
       async clear(queue) {
         await this.dbService.execute(`DELETE FROM ${this.tableName} WHERE queue = $1`, [queue]);
       }
       /**
-       * 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.
        */
       async popBlocking(queue, timeout) {
         const start = Date.now();
@@ -258,12 +584,14 @@ var init_DatabaseDriver = __esm({
           if (timeout > 0 && Date.now() - start >= timeoutMs) {
             return null;
           }
-          await new Promise((resolve) => setTimeout(resolve, 1e3));
+          await new Promise((resolve2) => setTimeout(resolve2, 1e3));
         }
       }
       /**
-       * 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.
        */
       async pushMany(queue, jobs) {
         if (jobs.length === 0) {
@@ -285,7 +613,10 @@ var init_DatabaseDriver = __esm({
         });
       }
       /**
-       * 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.
        */
       async fail(queue, job) {
         const failedQueue = `failed:${queue}`;
@@ -297,7 +628,10 @@ var init_DatabaseDriver = __esm({
         );
       }
       /**
-       * Acknowledge/Complete a job.
+       * Deletes a job row from the database (completion).
+       *
+       * @param _queue - The queue name (unused).
+       * @param job - The job to complete.
        */
       async complete(_queue, job) {
         if (!job.id) {
@@ -351,7 +685,10 @@ var init_KafkaDriver = __esm({
         return this.admin;
       }
       /**
-       * Push a job to a topic.
+       * Pushes a job to a Kafka topic.
+       *
+       * @param queue - The topic name.
+       * @param job - The job to publish.
        */
       async push(queue, job) {
         const producer = await this.ensureProducer();
@@ -376,30 +713,37 @@ var init_KafkaDriver = __esm({
         });
       }
       /**
-       * Pop is not supported for Kafka.
+       * Pop is not supported for Kafka (Push-based).
+       *
+       * Kafka consumers typically stream messages. Use `subscribe()` instead.
        *
-       * Note: Kafka uses a push-based model, so you should use `subscribe()`.
+       * @throws {Error} Always throws as Kafka does not support polling individual messages in this manner.
        */
       async pop(_queue) {
         throw new Error("[KafkaDriver] Kafka uses push-based model. Use subscribe() instead of pop().");
       }
       /**
-       * 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.
        */
       async size(_queue) {
         return 0;
       }
       /**
-       * Clear a queue by deleting the topic.
+       * Clears a queue by deleting the topic.
+       *
+       * @param queue - The topic name.
        */
       async clear(queue) {
         const admin = await this.ensureAdmin();
         await admin.deleteTopics({ topics: [queue] });
       }
       /**
-       * Push multiple jobs.
+       * Pushes multiple jobs to a Kafka topic.
+       *
+       * @param queue - The topic name.
+       * @param jobs - Array of jobs.
        */
       async pushMany(queue, jobs) {
         if (jobs.length === 0) {
@@ -428,7 +772,10 @@ var init_KafkaDriver = __esm({
         });
       }
       /**
-       * Create a topic.
+       * Creates a new Kafka topic.
+       *
+       * @param topic - The topic name.
+       * @param options - Config for partitions/replication.
        */
       async createTopic(topic, options) {
         const admin = await this.ensureAdmin();
@@ -443,13 +790,20 @@ var init_KafkaDriver = __esm({
         });
       }
       /**
-       * Delete a topic.
+       * Deletes a Kafka topic.
+       *
+       * @param topic - The topic name.
        */
       async deleteTopic(topic) {
         await this.clear(topic);
       }
       /**
-       * 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.
        */
       async subscribe(queue, callback) {
         const consumer = this.client.consumer({ groupId: this.consumerGroupId });
@@ -535,7 +889,10 @@ var init_RabbitMQDriver = __esm({
         return this.connection;
       }
       /**
-       * Push a job (sendToQueue / publish).
+       * Pushes a job to a RabbitMQ queue or exchange.
+       *
+       * @param queue - The queue name.
+       * @param job - The serialized job.
        */
       async push(queue, job) {
         const channel = await this.ensureChannel();
@@ -550,7 +907,9 @@ var init_RabbitMQDriver = __esm({
         }
       }
       /**
-       * Pop a job (get).
+       * Pops a job from the queue.
+       *
+       * @param queue - The queue name.
        */
       async pop(queue) {
         const channel = await this.ensureChannel();
@@ -564,8 +923,10 @@ var init_RabbitMQDriver = __esm({
         return job;
       }
       /**
-       * 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.
        */
       async popMany(queue, count) {
         const channel = await this.ensureChannel();
@@ -583,7 +944,9 @@ var init_RabbitMQDriver = __esm({
         return results;
       }
       /**
-       * Acknowledge a message.
+       * Acknowledges a message.
+       *
+       * @param messageId - The message object (RabbitMQ requires object reference).
        */
       async acknowledge(messageId) {
         const channel = await this.ensureChannel();
@@ -606,7 +969,7 @@ var init_RabbitMQDriver = __esm({
         channel.reject(message, requeue);
       }
       /**
-       * Subscribe to a queue.
+       * Subscribes to a queue.
        */
       async subscribe(queue, callback, options = {}) {
         const channel = await this.ensureChannel();
@@ -635,7 +998,9 @@ var init_RabbitMQDriver = __esm({
         );
       }
       /**
-       * Get queue size.
+       * Returns the number of messages in the queue.
+       *
+       * @param queue - The queue name.
        */
       async size(queue) {
         const channel = await this.ensureChannel();
@@ -643,7 +1008,9 @@ var init_RabbitMQDriver = __esm({
         return ok.messageCount;
       }
       /**
-       * Clear a queue.
+       * Purges the queue.
+       *
+       * @param queue - The queue name.
        */
       async clear(queue) {
         const channel = await this.ensureChannel();
@@ -691,7 +1058,7 @@ var init_RedisDriver = __esm({
     local activeSet = KEYS[2]
     local pendingList = KEYS[3]
     local groupId = ARGV[1]
-
+    
     local nextJob = redis.call('LPOP', pendingList)
     if nextJob then
       return redis.call('LPUSH', waitList, nextJob)
@@ -789,7 +1156,13 @@ var init_RedisDriver = __esm({
         return `${this.prefix}${queue}`;
       }
       /**
-       * 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.
        */
       async push(queue, job, options) {
         const key = this.getKey(queue, options?.priority);
@@ -810,6 +1183,9 @@ var init_RedisDriver = __esm({
           failedAt: job.failedAt
         };
         const payload = JSON.stringify(payloadObj);
+        if (typeof this.client.sadd === "function") {
+          await this.client.sadd(`${this.prefix}queues`, queue);
+        }
         if (groupId && typeof this.client.pushGroupJob === "function") {
           const activeSetKey = `${this.prefix}active`;
           const pendingListKey = `${this.prefix}pending:${groupId}`;
@@ -829,7 +1205,12 @@ var init_RedisDriver = __esm({
         }
       }
       /**
-       * 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.
        */
       async complete(queue, job) {
         if (!job.groupId) {
@@ -843,8 +1224,13 @@ var init_RedisDriver = __esm({
         }
       }
       /**
-       * 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`.
        */
       async pop(queue) {
         const priorities = ["critical", "high", "default", "low"];
@@ -916,8 +1302,12 @@ var init_RedisDriver = __esm({
         return null;
       }
       /**
-       * 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.
        */
       async popBlocking(queues, timeout) {
         const queueList = Array.isArray(queues) ? queues : [queues];
@@ -961,14 +1351,19 @@ var init_RedisDriver = __esm({
         };
       }
       /**
-       * Get queue size.
+       * Returns the length of the queue (Redis List length).
+       *
+       * @param queue - The queue name.
        */
       async size(queue) {
         const key = this.getKey(queue);
         return this.client.llen(key);
       }
       /**
-       * 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.
        */
       async fail(queue, job) {
         const key = `${this.getKey(queue)}:failed`;
@@ -982,7 +1377,9 @@ var init_RedisDriver = __esm({
         }
       }
       /**
-       * Clear a queue.
+       * Clears the queue and its associated delayed/active sets.
+       *
+       * @param queue - The queue name.
        */
       async clear(queue) {
         const key = this.getKey(queue);
@@ -995,8 +1392,11 @@ var init_RedisDriver = __esm({
         }
       }
       /**
-       * 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.
        */
       async stats(queue) {
         const priorities = ["critical", "high", "default", "low"];
@@ -1041,7 +1441,12 @@ var init_RedisDriver = __esm({
         return stats;
       }
       /**
-       * 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.
        */
       async pushMany(queue, jobs) {
         if (jobs.length === 0) {
@@ -1113,8 +1518,12 @@ var init_RedisDriver = __esm({
         await this.client.lpush(key, ...payloads);
       }
       /**
-       * 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.
        */
       async popMany(queue, count) {
         if (count <= 0) {
@@ -1192,7 +1601,9 @@ var init_RedisDriver = __esm({
         return results;
       }
       /**
-       * Report worker heartbeat for monitoring.
+       * Reports a worker heartbeat.
+       *
+       * Stores worker metadata in a key with an expiration (TTL).
        */
       async reportHeartbeat(workerInfo, prefix) {
         const key = `${prefix ?? this.prefix}worker:${workerInfo.id}`;
@@ -1201,7 +1612,9 @@ var init_RedisDriver = __esm({
         }
       }
       /**
-       * Publish a log message for monitoring.
+       * Publishes monitoring logs.
+       *
+       * Uses Redis Pub/Sub for real-time logs and a capped List for history.
        */
       async publishLog(logPayload, prefix) {
         const payload = JSON.stringify(logPayload);
@@ -1220,8 +1633,12 @@ var init_RedisDriver = __esm({
         }
       }
       /**
-       * 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.
        */
       async checkRateLimit(queue, config) {
         const key = `${this.prefix}${queue}:ratelimit`;
@@ -1239,7 +1656,11 @@ var init_RedisDriver = __esm({
         return true;
       }
       /**
-       * Get failed jobs from DLQ.
+       * Retrieves failed jobs from the DLQ.
+       *
+       * @param queue - The queue name.
+       * @param start - Start index.
+       * @param end - End index.
        */
       async getFailed(queue, start = 0, end = -1) {
         const key = `${this.getKey(queue)}:failed`;
@@ -1250,8 +1671,12 @@ var init_RedisDriver = __esm({
         return payloads.map((p) => this.parsePayload(p));
       }
       /**
-       * 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.
        */
       async retryFailed(queue, count = 1) {
         const failedKey = `${this.getKey(queue)}:failed`;
@@ -1268,18 +1693,31 @@ var init_RedisDriver = __esm({
           job.attempts = 0;
           delete job.error;
           delete job.failedAt;
+          delete job.priority;
           await this.push(queue, job, { priority: job.priority, groupId: job.groupId });
           retried++;
         }
         return retried;
       }
       /**
-       * Clear failed jobs from DLQ.
+       * Clears the Dead Letter Queue.
+       *
+       * @param queue - The queue name.
        */
       async clearFailed(queue) {
         const key = `${this.getKey(queue)}:failed`;
         await this.client.del(key);
       }
+      /**
+       * Retrieves all discovered queue names from Redis.
+       */
+      async getQueues() {
+        if (typeof this.client.smembers === "function") {
+          const queues = await this.client.smembers(`${this.prefix}queues`);
+          return Array.isArray(queues) ? queues.sort() : [];
+        }
+        return ["default"];
+      }
     };
   }
 });
@@ -1326,7 +1764,10 @@ var init_SQSDriver = __esm({
         return queue;
       }
       /**
-       * Push a job to SQS.
+       * Pushes a job to SQS.
+       *
+       * @param queue - The queue name (or URL).
+       * @param job - The serialized job.
        */
       async push(queue, job) {
         const { SendMessageCommand } = await import("@aws-sdk/client-sqs");
@@ -1351,7 +1792,9 @@ var init_SQSDriver = __esm({
         );
       }
       /**
-       * Pop a job (long polling).
+       * Pops a job from SQS (using long polling).
+       *
+       * @param queue - The queue name (or URL).
        */
       async pop(queue) {
         const { ReceiveMessageCommand } = await import("@aws-sdk/client-sqs");
@@ -1383,8 +1826,10 @@ var init_SQSDriver = __esm({
         };
       }
       /**
-       * 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).
        */
       async popMany(queue, count) {
         const { ReceiveMessageCommand } = await import("@aws-sdk/client-sqs");
@@ -1417,7 +1862,9 @@ var init_SQSDriver = __esm({
         });
       }
       /**
-       * Get queue size (approximate).
+       * Returns the approximate number of messages in the queue.
+       *
+       * @param queue - The queue name.
        */
       async size(queue) {
         const { GetQueueAttributesCommand } = await import("@aws-sdk/client-sqs");
@@ -1436,10 +1883,12 @@ var init_SQSDriver = __esm({
         }
       }
       /**
-       * Clear a queue by receiving and deleting messages.
+       * Clears the queue by continuously receiving and deleting messages.
        *
-       * 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.
+       * SQS does not have a "purge" command in the client data plane easily accessible here,
+       * so we drain the queue.
+       *
+       * @param queue - The queue name.
        */
       async clear(queue) {
         const { DeleteMessageCommand } = await import("@aws-sdk/client-sqs");
@@ -1460,7 +1909,10 @@ var init_SQSDriver = __esm({
         }
       }
       /**
-       * Push multiple jobs.
+       * Pushes multiple jobs using SQS batch API.
+       *
+       * @param queue - The queue name.
+       * @param jobs - Array of jobs.
        */
       async pushMany(queue, jobs) {
         if (jobs.length === 0) {
@@ -1497,13 +1949,16 @@ var init_SQSDriver = __esm({
         }
       }
       /**
-       * Acknowledge is not supported via messageId.
+       * Throws error as SQS requires ReceiptHandle, not just MessageId.
        */
       async acknowledge(_messageId) {
         throw new Error("[SQSDriver] Use deleteMessage() with ReceiptHandle instead of acknowledge().");
       }
       /**
-       * Delete a message (acknowledge processing completion).
+       * Deletes a message using its ReceiptHandle (ACK).
+       *
+       * @param queue - The queue name.
+       * @param receiptHandle - The SQS receipt handle.
        */
       async deleteMessage(queue, receiptHandle) {
         const { DeleteMessageCommand } = await import("@aws-sdk/client-sqs");
@@ -1519,42 +1974,254 @@ var init_SQSDriver = __esm({
   }
 });
 
-// src/persistence/BufferedPersistence.ts
-var BufferedPersistence_exports = {};
-__export(BufferedPersistence_exports, {
-  BufferedPersistence: () => BufferedPersistence
-});
-var BufferedPersistence;
-var init_BufferedPersistence = __esm({
-  "src/persistence/BufferedPersistence.ts"() {
+// src/locks/DistributedLock.ts
+var DistributedLock;
+var init_DistributedLock = __esm({
+  "src/locks/DistributedLock.ts"() {
     "use strict";
-    BufferedPersistence = class {
-      constructor(adapter, options = {}) {
-        this.adapter = adapter;
-        this.maxBufferSize = options.maxBufferSize ?? 50;
-        this.flushInterval = options.flushInterval ?? 5e3;
-      }
-      jobBuffer = [];
-      logBuffer = [];
-      flushTimer = null;
-      maxBufferSize;
-      flushInterval;
-      async archive(queue, job, status) {
-        this.jobBuffer.push({ queue, job, status });
-        if (this.jobBuffer.length >= this.maxBufferSize) {
-          this.flush().catch((err) => {
-            console.error("[BufferedPersistence] Auto-flush failed (jobs):", err.message || err);
-          });
-        } else {
-          this.ensureFlushTimer();
-        }
-      }
-      async find(queue, id) {
-        return this.adapter.find(queue, id);
+    DistributedLock = class {
+      /**
+       * Creates a DistributedLock instance.
+       *
+       * @param client - Redis client instance. Must support SET, DEL, and EVAL commands.
+       */
+      constructor(client) {
+        this.client = client;
       }
-      async list(queue, options) {
+      /**
+       * Unique identifier for this lock instance.
+       * Used to ensure only the owner can release the lock.
+       */
+      lockId = crypto.randomUUID();
+      /**
+       * Timer for automatic renewal.
+       */
+      refreshTimer = null;
+      /**
+       * The key of the currently held lock.
+       */
+      currentLockKey = null;
+      /**
+       * 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');
+       * }
+       * ```
+       */
+      async acquire(key, options) {
+        if (typeof this.client.set !== "function") {
+          throw new Error("[DistributedLock] Redis client does not support SET command");
+        }
+        const ttlSeconds = Math.ceil(options.ttl / 1e3);
+        let attempts = 0;
+        while (attempts <= options.retryCount) {
+          try {
+            const result = await this.client.set(key, this.lockId, "EX", ttlSeconds, "NX");
+            if (result === "OK") {
+              this.currentLockKey = key;
+              if (options.refreshInterval) {
+                this.startRefresh(key, options);
+              }
+              return true;
+            }
+          } catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            console.error(`[DistributedLock] Failed to acquire lock for ${key}:`, err.message);
+          }
+          attempts++;
+          if (attempts <= options.retryCount) {
+            await this.sleep(options.retryDelay);
+          }
+        }
+        return false;
+      }
+      /**
+       * 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');
+       * ```
+       */
+      async release(key) {
+        this.stopRefresh();
+        if (typeof this.client.eval !== "function") {
+          throw new Error("[DistributedLock] Redis client does not support EVAL command");
+        }
+        try {
+          const script = `
+        if redis.call("get", KEYS[1]) == ARGV[1] then
+          return redis.call("del", KEYS[1])
+        else
+          return 0
+        end
+      `;
+          await this.client.eval(script, 1, key, this.lockId);
+          this.currentLockKey = null;
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          console.error(`[DistributedLock] Failed to release lock for ${key}:`, err.message);
+        }
+      }
+      /**
+       * 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`.
+       */
+      startRefresh(key, options) {
+        if (!options.refreshInterval) {
+          return;
+        }
+        this.stopRefresh();
+        const ttlSeconds = Math.ceil(options.ttl / 1e3);
+        this.refreshTimer = setInterval(async () => {
+          try {
+            if (typeof this.client.eval !== "function") {
+              console.error("[DistributedLock] Redis client does not support EVAL command for refresh");
+              return;
+            }
+            const script = `
+          if redis.call("get", KEYS[1]) == ARGV[1] then
+            return redis.call("expire", KEYS[1], ARGV[2])
+          else
+            return 0
+          end
+        `;
+            const result = await this.client.eval(script, 1, key, this.lockId, ttlSeconds);
+            if (result === 0) {
+              console.warn(
+                `[DistributedLock] Lock ${key} no longer held by this instance, stopping refresh`
+              );
+              this.stopRefresh();
+            }
+          } catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            console.error(`[DistributedLock] Failed to refresh lock ${key}:`, err.message);
+          }
+        }, options.refreshInterval);
+      }
+      /**
+       * Stops the automatic renewal timer.
+       */
+      stopRefresh() {
+        if (this.refreshTimer) {
+          clearInterval(this.refreshTimer);
+          this.refreshTimer = null;
+        }
+      }
+      /**
+       * Helper for delay.
+       *
+       * @param ms - Milliseconds to sleep.
+       */
+      sleep(ms) {
+        return new Promise((resolve2) => setTimeout(resolve2, ms));
+      }
+      /**
+       * 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) {
+        return this.currentLockKey === key;
+      }
+    };
+  }
+});
+
+// src/persistence/BufferedPersistence.ts
+var BufferedPersistence_exports = {};
+__export(BufferedPersistence_exports, {
+  BufferedPersistence: () => BufferedPersistence
+});
+var BufferedPersistence;
+var init_BufferedPersistence = __esm({
+  "src/persistence/BufferedPersistence.ts"() {
+    "use strict";
+    BufferedPersistence = class {
+      constructor(adapter, options = {}) {
+        this.adapter = adapter;
+        this.maxBufferSize = options.maxBufferSize ?? 50;
+        this.flushInterval = options.flushInterval ?? 5e3;
+      }
+      jobBuffer = [];
+      logBuffer = [];
+      flushTimer = null;
+      maxBufferSize;
+      flushInterval;
+      /**
+       * Buffers a job archive request.
+       *
+       * @param queue - The queue name.
+       * @param job - The serialized job.
+       * @param status - The final job status.
+       */
+      async archive(queue, job, status) {
+        this.jobBuffer.push({ queue, job, status });
+        if (this.jobBuffer.length >= this.maxBufferSize) {
+          this.flush().catch((err) => {
+            console.error("[BufferedPersistence] Auto-flush failed (jobs):", err.message || err);
+          });
+        } else {
+          this.ensureFlushTimer();
+        }
+      }
+      /**
+       * Delegates find to the underlying adapter (no buffering for reads).
+       */
+      async find(queue, id) {
+        return this.adapter.find(queue, id);
+      }
+      /**
+       * Delegates list to the underlying adapter (no buffering for reads).
+       */
+      async list(queue, options) {
         return this.adapter.list(queue, options);
       }
+      /**
+       * Archives multiple jobs directly (bypassing buffer, or flushing first).
+       *
+       * Actually, for consistency, this might just pass through.
+       */
       async archiveMany(jobs) {
         if (this.adapter.archiveMany) {
           return this.adapter.archiveMany(jobs);
@@ -1563,9 +2230,17 @@ var init_BufferedPersistence = __esm({
           await this.adapter.archive(item.queue, item.job, item.status);
         }
       }
+      /**
+       * Delegates cleanup to the underlying adapter.
+       */
       async cleanup(days) {
         return this.adapter.cleanup(days);
       }
+      /**
+       * Flushes all buffered data to the underlying adapter.
+       *
+       * Uses `archiveMany` and `archiveLogMany` if supported by the adapter for batch efficiency.
+       */
       async flush() {
         if (this.flushTimer) {
           clearTimeout(this.flushTimer);
@@ -1604,9 +2279,15 @@ var init_BufferedPersistence = __esm({
         }
         await Promise.all(promises);
       }
+      /**
+       * Delegates count to the underlying adapter.
+       */
       async count(queue, options) {
         return this.adapter.count(queue, options);
       }
+      /**
+       * Buffers a log message.
+       */
       async archiveLog(log) {
         this.logBuffer.push(log);
         if (this.logBuffer.length >= this.maxBufferSize) {
@@ -1617,6 +2298,9 @@ var init_BufferedPersistence = __esm({
           this.ensureFlushTimer();
         }
       }
+      /**
+       * Archives multiple logs directly.
+       */
       async archiveLogMany(logs) {
         if (this.adapter.archiveLogMany) {
           return this.adapter.archiveLogMany(logs);
@@ -1625,12 +2309,21 @@ var init_BufferedPersistence = __esm({
           await this.adapter.archiveLog(log);
         }
       }
+      /**
+       * Delegates listLogs to the underlying adapter.
+       */
       async listLogs(options) {
         return this.adapter.listLogs(options);
       }
+      /**
+       * Delegates countLogs to the underlying adapter.
+       */
       async countLogs(options) {
         return this.adapter.countLogs(options);
       }
+      /**
+       * Ensures the auto-flush timer is running.
+       */
       ensureFlushTimer() {
         if (this.flushTimer) {
           return;
@@ -3294,6 +3987,9 @@ var init_MessagePackSerializer = __esm({
           );
         }
       }
+      /**
+       * Serialize a job using MessagePack.
+       */
       serialize(job) {
         const id = job.id || `${Date.now()}-${crypto.randomUUID()}`;
         const properties = {};
@@ -3316,6 +4012,9 @@ var init_MessagePackSerializer = __esm({
           ...job.priority ? { priority: job.priority } : {}
         };
       }
+      /**
+       * Deserialize a MessagePack job.
+       */
       deserialize(serialized) {
         if (serialized.type !== "msgpack") {
           throw new Error('Invalid serialization type: expected "msgpack"');
@@ -3353,12 +4052,29 @@ var init_Scheduler = __esm({
   "src/Scheduler.ts"() {
     "use strict";
     import_cron_parser = __toESM(require("cron-parser"), 1);
+    init_DistributedLock();
     Scheduler = class {
       constructor(manager, options = {}) {
         this.manager = manager;
         this.prefix = options.prefix ?? "queue:";
+        this.lockTtl = options.lockTtl ?? 6e4;
+        this.lockRefreshInterval = options.lockRefreshInterval ?? 2e4;
+        this.lockRetryCount = options.lockRetryCount ?? 0;
+        this.lockRetryDelay = options.lockRetryDelay ?? 100;
+        this.tickInterval = options.tickInterval ?? 6e4;
+        this.leaderTtl = options.leaderTtl ?? 3e4;
       }
       prefix;
+      lockTtl;
+      lockRefreshInterval;
+      lockRetryCount;
+      lockRetryDelay;
+      tickInterval;
+      leaderTtl;
+      distributedLock;
+      running = false;
+      timer = null;
+      isLeader = false;
       get client() {
         const driver = this.manager.getDriver(this.manager.getDefaultConnection());
         if (!driver || !("client" in driver)) {
@@ -3367,7 +4083,23 @@ var init_Scheduler = __esm({
         return driver.client;
       }
       /**
-       * Register a scheduled job.
+       * Gets or creates the distributed lock instance.
+       *
+       * @private
+       */
+      getDistributedLock() {
+        if (!this.distributedLock) {
+          this.distributedLock = new DistributedLock(this.client);
+        }
+        return this.distributedLock;
+      }
+      /**
+       * 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.
        */
       async register(config) {
         const nextRun = import_cron_parser.default.parse(config.cron).next().getTime();
@@ -3389,7 +4121,11 @@ var init_Scheduler = __esm({
         await pipe.exec();
       }
       /**
-       * 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.
        */
       async remove(id) {
         const client = this.client;
@@ -3402,7 +4138,9 @@ var init_Scheduler = __esm({
         await pipe.exec();
       }
       /**
-       * List all scheduled jobs.
+       * Lists all registered scheduled jobs.
+       *
+       * @returns An array of all scheduled job configurations.
        */
       async list() {
         const client = this.client;
@@ -3426,7 +4164,77 @@ var init_Scheduler = __esm({
         return configs;
       }
       /**
-       * 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.
+       */
+      async start() {
+        if (this.running) {
+          return;
+        }
+        this.running = true;
+        const loop = async () => {
+          if (!this.running) {
+            return;
+          }
+          try {
+            await this.performTickWithLeaderElection();
+          } catch (err) {
+            console.error("[Scheduler] Loop error:", err);
+          }
+          this.timer = setTimeout(loop, this.tickInterval);
+        };
+        loop();
+      }
+      /**
+       * Stops the automatic scheduler loop.
+       */
+      async stop() {
+        this.running = false;
+        if (this.timer) {
+          clearTimeout(this.timer);
+          this.timer = null;
+        }
+        if (this.isLeader) {
+          await this.releaseLeader();
+        }
+      }
+      /**
+       * Acquires the leader lock and performs a tick.
+       *
+       * @private
+       */
+      async performTickWithLeaderElection() {
+        const lock = this.getDistributedLock();
+        const leaderKey = `${this.prefix}scheduler:leader`;
+        this.isLeader = await lock.acquire(leaderKey, {
+          ttl: this.leaderTtl,
+          refreshInterval: Math.floor(this.leaderTtl / 3),
+          retryCount: 0,
+          retryDelay: 0
+        });
+        if (this.isLeader) {
+          await this.tick();
+        }
+      }
+      /**
+       * Releases the leader lock.
+       *
+       * @private
+       */
+      async releaseLeader() {
+        const lock = this.getDistributedLock();
+        const leaderKey = `${this.prefix}scheduler:leader`;
+        await lock.release(leaderKey);
+        this.isLeader = false;
+      }
+      /**
+       * 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.
        */
       async runNow(id) {
         const client = this.client;
@@ -3439,8 +4247,16 @@ var init_Scheduler = __esm({
         }
       }
       /**
-       * 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.
        */
       async tick() {
         const client = this.client;
@@ -3450,35 +4266,42 @@ var init_Scheduler = __esm({
         const now = Date.now();
         const dueIds = await client.zrangebyscore(`${this.prefix}schedules`, 0, now);
         let fired = 0;
+        const lock = this.getDistributedLock();
         for (const id of dueIds) {
           const lockKey = `${this.prefix}lock:schedule:${id}:${Math.floor(now / 1e3)}`;
-          if (typeof client.set !== "function") {
-            continue;
-          }
-          const lock = await client.set(lockKey, "1", "EX", 10, "NX");
-          if (lock === "OK") {
-            const data = await client.hgetall?.(`${this.prefix}schedule:${id}`);
-            if (data?.id && data.enabled === "true") {
-              try {
-                const serializedJob = JSON.parse(data.job);
-                const connection = data.connection || this.manager.getDefaultConnection();
-                const driver = this.manager.getDriver(connection);
-                await driver.push(data.queue, serializedJob);
-                const nextRun = import_cron_parser.default.parse(data.cron).next().getTime();
-                if (typeof client.pipeline === "function") {
-                  const pipe = client.pipeline();
-                  pipe.hset(`${this.prefix}schedule:${id}`, {
-                    lastRun: now,
-                    nextRun
-                  });
-                  pipe.zadd(`${this.prefix}schedules`, nextRun, id);
-                  await pipe.exec();
+          const acquired = await lock.acquire(lockKey, {
+            ttl: this.lockTtl,
+            retryCount: this.lockRetryCount,
+            retryDelay: this.lockRetryDelay,
+            refreshInterval: this.lockRefreshInterval
+          });
+          if (acquired) {
+            try {
+              const data = await client.hgetall?.(`${this.prefix}schedule:${id}`);
+              if (data?.id && data.enabled === "true") {
+                try {
+                  const serializedJob = JSON.parse(data.job);
+                  const connection = data.connection || this.manager.getDefaultConnection();
+                  const driver = this.manager.getDriver(connection);
+                  await driver.push(data.queue, serializedJob);
+                  const nextRun = import_cron_parser.default.parse(data.cron).next().getTime();
+                  if (typeof client.pipeline === "function") {
+                    const pipe = client.pipeline();
+                    pipe.hset(`${this.prefix}schedule:${id}`, {
+                      lastRun: now,
+                      nextRun
+                    });
+                    pipe.zadd(`${this.prefix}schedules`, nextRun, id);
+                    await pipe.exec();
+                  }
+                  fired++;
+                } catch (err) {
+                  const error = err instanceof Error ? err : new Error(String(err));
+                  console.error(`[Scheduler] Failed to process schedule ${id}:`, error.message);
                 }
-                fired++;
-              } catch (err) {
-                const error = err instanceof Error ? err : new Error(String(err));
-                console.error(`[Scheduler] Failed to process schedule ${id}:`, error.message);
               }
+            } finally {
+              await lock.release(lockKey);
             }
           }
         }
@@ -3488,13 +4311,112 @@ var init_Scheduler = __esm({
   }
 });
 
+// src/DashboardProvider.ts
+var DashboardProvider_exports = {};
+__export(DashboardProvider_exports, {
+  DashboardProvider: () => DashboardProvider
+});
+var DashboardProvider;
+var init_DashboardProvider = __esm({
+  "src/DashboardProvider.ts"() {
+    "use strict";
+    DashboardProvider = class {
+      constructor(manager) {
+        this.manager = manager;
+      }
+      /**
+       * Registers dashboard API routes on the provided core adapter.
+       *
+       * @param core - The PlanetCore instance.
+       * @param basePath - The base path for API routes (default: '/_flux').
+       */
+      registerRoutes(core, basePath = "/_flux") {
+        const router = core.adapter;
+        router.get(`${basePath}/stats`, async (c) => {
+          const stats = await this.manager.getGlobalStats();
+          return c.json(stats);
+        });
+        router.get(`${basePath}/queues`, async (c) => {
+          const stats = await this.manager.getGlobalStats();
+          const queues = Object.entries(stats.connections).flatMap(
+            ([conn, qList]) => qList.map((q) => ({
+              connection: conn,
+              name: q.queue,
+              size: q.size,
+              failed: q.failed
+            }))
+          );
+          return c.json(queues);
+        });
+        router.get(`${basePath}/jobs`, async (c) => {
+          const queue = c.req.query("queue") || "default";
+          const status = c.req.query("status");
+          const limit = parseInt(c.req.query("limit") || "50", 10);
+          const offset = parseInt(c.req.query("offset") || "0", 10);
+          const persistence = this.manager.getPersistence();
+          if (!persistence) {
+            return c.json({ error: "Persistence not configured" }, 400);
+          }
+          const statuses = status ? status.includes(",") ? status.split(",") : status : void 0;
+          const [jobs, total] = await Promise.all([
+            persistence.list(queue, { status: statuses, limit, offset }),
+            persistence.count(queue, { status: statuses })
+          ]);
+          return c.json({
+            data: jobs,
+            meta: {
+              total,
+              limit,
+              offset
+            }
+          });
+        });
+        router.post(`${basePath}/jobs/retry`, async (c) => {
+          const { queue, count } = await c.req.json();
+          if (!queue) {
+            return c.json({ error: "Queue name is required" }, 400);
+          }
+          const retried = await this.manager.retryFailed(queue, count || 1);
+          return c.json({ success: true, retried });
+        });
+        router.get(`${basePath}/logs`, async (c) => {
+          const persistence = this.manager.getPersistence();
+          if (!persistence) {
+            return c.json({ error: "Persistence not configured" }, 400);
+          }
+          const limit = parseInt(c.req.query("limit") || "100", 10);
+          const offset = parseInt(c.req.query("offset") || "0", 10);
+          const level = c.req.query("level");
+          const search = c.req.query("search");
+          const [logs, total] = await Promise.all([
+            persistence.listLogs({ limit, offset, level, search }),
+            persistence.countLogs({ level, search })
+          ]);
+          return c.json({
+            data: logs,
+            meta: {
+              total,
+              limit,
+              offset
+            }
+          });
+        });
+      }
+    };
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BatchConsumer: () => BatchConsumer,
   BufferedPersistence: () => BufferedPersistence,
+  BullMQDriver: () => BullMQDriver,
   ClassNameSerializer: () => ClassNameSerializer,
   Consumer: () => Consumer,
   DatabaseDriver: () => DatabaseDriver,
+  DistributedLock: () => DistributedLock,
+  GrpcDriver: () => GrpcDriver,
   Job: () => Job,
   JsonSerializer: () => JsonSerializer,
   KafkaDriver: () => KafkaDriver,
@@ -3506,83 +4428,464 @@ __export(index_exports, {
   RedisDriver: () => RedisDriver,
   SQLitePersistence: () => SQLitePersistence,
   SQSDriver: () => SQSDriver,
+  SandboxedWorker: () => SandboxedWorker,
   Scheduler: () => Scheduler,
-  Worker: () => Worker
+  StreamEventBackend: () => StreamEventBackend,
+  SystemEventJob: () => SystemEventJob,
+  Worker: () => Worker,
+  WorkerPool: () => WorkerPool
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/Consumer.ts
-var import_node_events = require("events");
-var import_p_limit = __toESM(require("p-limit"), 1);
-
-// src/Worker.ts
-var Worker = class {
-  constructor(options = {}) {
-    this.options = options;
+// src/BatchConsumer.ts
+var BatchConsumer = class {
+  constructor(manager, handler, options = {}) {
+    this.manager = manager;
+    this.handler = handler;
+    this.options = {
+      queue: "default",
+      batchSize: 10,
+      pollInterval: 1e3,
+      autoAck: true,
+      ...options
+    };
   }
+  running = false;
+  options;
   /**
-   * Process a Job.
-   * @param job - Job instance
+   * Starts the batch consuming loop.
+   *
+   * Continuously polls for batches of jobs and passes them to the handler.
    */
-  async process(job) {
-    const maxAttempts = job.maxAttempts ?? this.options.maxAttempts ?? 3;
-    const timeout = this.options.timeout;
-    if (!job.attempts) {
-      job.attempts = 1;
+  async start() {
+    if (this.running) {
+      return;
     }
-    try {
-      if (timeout) {
-        await Promise.race([
-          job.handle(),
-          new Promise(
-            (_, reject) => setTimeout(
-              () => reject(new Error(`Job timeout after ${timeout} seconds`)),
-              timeout * 1e3
-            )
-          )
-        ]);
-      } else {
-        await job.handle();
-      }
-    } catch (error) {
-      const err = error instanceof Error ? error : new Error(String(error));
-      if (job.attempts >= maxAttempts) {
-        await this.handleFailure(job, err);
+    this.running = true;
+    const { queue, connection, batchSize, pollInterval, autoAck } = this.options;
+    while (this.running) {
+      try {
+        const jobs = await this.manager.popMany(queue, batchSize, connection);
+        if (jobs.length > 0) {
+          try {
+            await this.handler(jobs);
+            if (autoAck) {
+              await Promise.all(jobs.map((job) => this.manager.complete(job)));
+            }
+          } catch (error) {
+            console.error(`[BatchConsumer] Batch processing failed:`, error);
+            const err = error instanceof Error ? error : new Error(String(error));
+            if (autoAck) {
+              await Promise.all(jobs.map((job) => this.manager.fail(job, err)));
+            }
+          }
+        } else {
+          await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
+        }
+      } catch (err) {
+        console.error(`[BatchConsumer] Polling error:`, err);
+        await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
       }
-      throw err;
     }
   }
   /**
-   * Handle failure.
+   * Stops the consumer loop.
+   *
+   * Sets the running flag to false. The loop will exit after the current iteration finishes.
    */
-  async handleFailure(job, error) {
-    try {
-      await job.failed(error);
-    } catch (failedError) {
-      console.error("[Worker] Error in job.failed():", failedError);
-    }
-    if (this.options.onFailed) {
-      try {
-        await this.options.onFailed(job, error);
-      } catch (callbackError) {
+  stop() {
+    this.running = false;
+  }
+};
+
+// src/Consumer.ts
+var import_node_events = require("events");
+var import_p_limit = __toESM(require("p-limit"), 1);
+
+// src/workers/SandboxedWorker.ts
+var import_node_path = require("path");
+var import_node_worker_threads = require("worker_threads");
+var SandboxedWorker = class {
+  worker = null;
+  state = "initializing" /* INITIALIZING */;
+  config;
+  idleTimer = null;
+  executionTimer = null;
+  /**
+   * Creates a SandboxedWorker instance.
+   *
+   * @param config - Configuration options for the worker.
+   */
+  constructor(config = {}) {
+    this.config = {
+      maxExecutionTime: config.maxExecutionTime ?? 3e4,
+      maxMemory: config.maxMemory ?? 0,
+      isolateContexts: config.isolateContexts ?? false,
+      idleTimeout: config.idleTimeout ?? 6e4
+    };
+  }
+  /**
+   * Initializes the Worker Thread.
+   *
+   * @returns The active Worker Thread instance.
+   * @throws {Error} If worker initialization fails or times out.
+   */
+  async initWorker() {
+    if (this.worker && this.state !== "terminated" /* TERMINATED */) {
+      return this.worker;
+    }
+    const fs = require("fs");
+    let workerPath = (0, import_node_path.resolve)(__dirname, "job-executor.js");
+    if (!fs.existsSync(workerPath)) {
+      const tsPath = (0, import_node_path.resolve)(__dirname, "job-executor.ts");
+      if (fs.existsSync(tsPath)) {
+        workerPath = tsPath;
+      }
+    }
+    const execArgv = process.execArgv.slice();
+    if (workerPath.endsWith(".ts") && !process.env.BUN_BINARY_TARGET) {
+      if (!execArgv.includes("--loader")) {
+        execArgv.push("--loader", "ts-node/esm");
+      }
+    }
+    const resourceLimits = {};
+    if (this.config.maxMemory > 0) {
+      resourceLimits.maxOldGenerationSizeMb = this.config.maxMemory;
+      resourceLimits.maxYoungGenerationSizeMb = Math.min(this.config.maxMemory / 2, 128);
+    }
+    this.worker = new import_node_worker_threads.Worker(workerPath, {
+      resourceLimits: Object.keys(resourceLimits).length > 0 ? resourceLimits : void 0,
+      execArgv
+    });
+    this.state = "initializing" /* INITIALIZING */;
+    await new Promise((resolve2, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error("Worker initialization timeout"));
+      }, 5e3);
+      this.worker?.once("message", (message) => {
+        clearTimeout(timeout);
+        if (message.type === "ready") {
+          this.state = "ready" /* READY */;
+          resolve2();
+        } else {
+          reject(new Error("Unexpected worker message during initialization"));
+        }
+      });
+      this.worker?.once("error", (error) => {
+        clearTimeout(timeout);
+        reject(error);
+      });
+    });
+    this.worker.on("error", (error) => {
+      console.error("[SandboxedWorker] Worker error:", error);
+      this.state = "terminated" /* TERMINATED */;
+    });
+    this.worker.on("exit", (code) => {
+      if (code !== 0) {
+        console.error(`[SandboxedWorker] Worker exited with code ${code}`);
+      }
+      this.state = "terminated" /* TERMINATED */;
+    });
+    return this.worker;
+  }
+  /**
+   * Executes a job in the sandboxed environment.
+   *
+   * @param job - The serialized job data to execute.
+   * @throws {Error} If execution fails, times out, or the worker crashes.
+   */
+  async execute(job) {
+    if (this.config.isolateContexts) {
+      await this.terminate();
+    }
+    const worker = await this.initWorker();
+    this.state = "busy" /* BUSY */;
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+    }
+    try {
+      await Promise.race([this.executeInWorker(worker, job), this.createTimeoutPromise()]);
+    } finally {
+      this.state = "ready" /* READY */;
+      if (this.executionTimer) {
+        clearTimeout(this.executionTimer);
+        this.executionTimer = null;
+      }
+      if (!this.config.isolateContexts) {
+        this.startIdleTimer();
+      } else {
+        await this.terminate();
+      }
+    }
+  }
+  /**
+   * Internal method to send execution message to the worker thread.
+   *
+   * @param worker - The worker thread instance.
+   * @param job - Job data.
+   */
+  executeInWorker(worker, job) {
+    return new Promise((resolve2, reject) => {
+      const messageHandler = (message) => {
+        if (message.type === "success") {
+          cleanup();
+          resolve2();
+        } else if (message.type === "error") {
+          cleanup();
+          const error = new Error(message.error || "Job execution failed");
+          if (message.stack) {
+            error.stack = message.stack;
+          }
+          reject(error);
+        }
+      };
+      const errorHandler = (error) => {
+        cleanup();
+        reject(error);
+      };
+      const exitHandler = (code) => {
+        cleanup();
+        if (code !== 0) {
+          reject(new Error(`Worker exited unexpectedly with code ${code}`));
+        }
+      };
+      const cleanup = () => {
+        worker.off("message", messageHandler);
+        worker.off("error", errorHandler);
+        worker.off("exit", exitHandler);
+      };
+      worker.on("message", messageHandler);
+      worker.on("error", errorHandler);
+      worker.on("exit", exitHandler);
+      worker.postMessage({
+        type: "execute",
+        job
+      });
+    });
+  }
+  /**
+   * Creates a promise that rejects after the configured timeout.
+   */
+  createTimeoutPromise() {
+    return new Promise((_, reject) => {
+      this.executionTimer = setTimeout(() => {
+        this.terminate().catch(console.error);
+        reject(new Error(`Job execution timeout after ${this.config.maxExecutionTime}ms`));
+      }, this.config.maxExecutionTime);
+    });
+  }
+  /**
+   * Starts the idle timer to auto-terminate the worker.
+   */
+  startIdleTimer() {
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+    }
+    this.idleTimer = setTimeout(() => {
+      this.terminate().catch(console.error);
+    }, this.config.idleTimeout);
+  }
+  /**
+   * Terminates the Worker Thread immediately.
+   *
+   * Stops any running job and releases resources.
+   */
+  async terminate() {
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+    }
+    if (this.executionTimer) {
+      clearTimeout(this.executionTimer);
+      this.executionTimer = null;
+    }
+    if (this.worker) {
+      const worker = this.worker;
+      this.worker = null;
+      this.state = "terminated" /* TERMINATED */;
+      try {
+        await worker.terminate();
+      } catch (error) {
+        console.error("[SandboxedWorker] Error terminating worker:", error);
+      }
+    }
+  }
+  /**
+   * Gets the current state of the worker.
+   *
+   * @returns The current `WorkerState`.
+   */
+  getState() {
+    return this.state;
+  }
+  /**
+   * Checks if the worker is ready to accept a job.
+   *
+   * @returns `true` if ready, `false` otherwise.
+   */
+  isReady() {
+    return this.state === "ready" /* READY */;
+  }
+  /**
+   * Checks if the worker is currently executing a job.
+   *
+   * @returns `true` if busy, `false` otherwise.
+   */
+  isBusy() {
+    return this.state === "busy" /* BUSY */;
+  }
+};
+
+// src/Worker.ts
+var Worker = class {
+  constructor(options = {}) {
+    this.options = options;
+    if (options.sandboxed) {
+      this.sandboxedWorker = new SandboxedWorker(options.sandboxConfig);
+    }
+  }
+  sandboxedWorker;
+  /**
+   * 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).
+   */
+  async process(job) {
+    const maxAttempts = job.maxAttempts ?? this.options.maxAttempts ?? 3;
+    const timeout = this.options.timeout;
+    if (!job.attempts) {
+      job.attempts = 1;
+    }
+    try {
+      if (this.options.sandboxed && this.sandboxedWorker) {
+        await this.processSandboxed(job);
+      } else {
+        await this.processStandard(job, timeout);
+      }
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      if (job.attempts >= maxAttempts) {
+        await this.handleFailure(job, err);
+      }
+      throw err;
+    }
+  }
+  /**
+   * Processes a job in standard mode (directly in current process).
+   *
+   * @param job - The job to process.
+   * @param timeout - Optional timeout in seconds.
+   */
+  async processStandard(job, timeout) {
+    if (timeout) {
+      await Promise.race([
+        job.handle(),
+        new Promise(
+          (_, reject) => setTimeout(
+            () => reject(new Error(`Job timeout after ${timeout} seconds`)),
+            timeout * 1e3
+          )
+        )
+      ]);
+    } else {
+      await job.handle();
+    }
+  }
+  /**
+   * Processes a job in sandboxed mode (in Worker Thread).
+   *
+   * @param job - The job to process.
+   */
+  async processSandboxed(job) {
+    if (!this.sandboxedWorker) {
+      throw new Error("Sandboxed worker not initialized");
+    }
+    const serialized = this.serializeJob(job);
+    await this.sandboxedWorker.execute(serialized);
+  }
+  /**
+   * Serializes a Job instance for Worker Thread execution.
+   *
+   * @param job - The job to serialize.
+   * @returns Serialized job data.
+   */
+  serializeJob(job) {
+    const data = JSON.stringify(job);
+    return {
+      id: job.id ?? `job-${Date.now()}-${Math.random()}`,
+      type: "json",
+      data,
+      createdAt: Date.now(),
+      attempts: job.attempts,
+      maxAttempts: job.maxAttempts,
+      delaySeconds: job.delaySeconds,
+      groupId: job.groupId,
+      priority: job.priority,
+      retryAfterSeconds: job.retryAfterSeconds,
+      retryMultiplier: job.retryMultiplier
+    };
+  }
+  /**
+   * 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.
+   */
+  async handleFailure(job, error) {
+    try {
+      await job.failed(error);
+    } catch (failedError) {
+      console.error("[Worker] Error in job.failed():", failedError);
+    }
+    if (this.options.onFailed) {
+      try {
+        await this.options.onFailed(job, error);
+      } catch (callbackError) {
         console.error("[Worker] Error in onFailed callback:", callbackError);
       }
     }
   }
+  /**
+   * Terminates the sandboxed worker and releases resources.
+   *
+   * Should be called when the worker is no longer needed.
+   * Only applicable when running in sandboxed mode.
+   */
+  async terminate() {
+    if (this.sandboxedWorker) {
+      await this.sandboxedWorker.terminate();
+    }
+  }
 };
 
 // src/Consumer.ts
-var Consumer = class extends import_node_events.EventEmitter {
+var Consumer = class _Consumer extends import_node_events.EventEmitter {
   constructor(queueManager, options) {
     super();
     this.queueManager = queueManager;
     this.options = options;
   }
+  /**
+   * Group limiter 的存活時間（毫秒）。
+   * 超過此時間未使用的 group limiter 會被清理，避免記憶體洩漏。
+   */
+  static GROUP_LIMITER_TTL = 6e4;
   running = false;
   stopRequested = false;
   workerId = `worker-${crypto.randomUUID()}`;
   heartbeatTimer = null;
+  cleanupTimer = null;
   groupLimiters = /* @__PURE__ */ new Map();
+  groupLimiterLastUsed = /* @__PURE__ */ new Map();
   stats = {
     processed: 0,
     failed: 0,
@@ -3593,7 +4896,7 @@ var Consumer = class extends import_node_events.EventEmitter {
     return this.options.connection ?? this.queueManager.getDefaultConnection();
   }
   /**
-   * Log debug message.
+   * Logs a debug message if debug mode is enabled.
    */
   log(message, data) {
     if (this.options.debug) {
@@ -3607,7 +4910,12 @@ var Consumer = class extends import_node_events.EventEmitter {
     }
   }
   /**
-   * Start the consumer loop.
+   * 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.
    */
   async start() {
     if (this.running) {
@@ -3639,10 +4947,11 @@ var Consumer = class extends import_node_events.EventEmitter {
         `Consumer started on [${this.options.queues.join(", ")}] with concurrency ${concurrency}`
       );
     }
+    this.startCleanupTimer();
     while (this.running && !this.stopRequested) {
       const capacity = concurrency - this.stats.active;
       if (capacity <= 0) {
-        await new Promise((resolve) => setTimeout(resolve, 50));
+        await new Promise((resolve2) => setTimeout(resolve2, 50));
         continue;
       }
       const eligibleQueues = [];
@@ -3664,7 +4973,7 @@ var Consumer = class extends import_node_events.EventEmitter {
         eligibleQueues.push(queue);
       }
       if (eligibleQueues.length === 0) {
-        await new Promise((resolve) => setTimeout(resolve, currentPollInterval));
+        await new Promise((resolve2) => setTimeout(resolve2, currentPollInterval));
         continue;
       }
       let jobs = [];
@@ -3713,7 +5022,7 @@ var Consumer = class extends import_node_events.EventEmitter {
               this.stats.active--;
             });
           }
-          await new Promise((resolve) => setTimeout(resolve, 0));
+          await new Promise((resolve2) => setTimeout(resolve2, 0));
           continue;
         }
       } catch (error) {
@@ -3724,22 +5033,23 @@ var Consumer = class extends import_node_events.EventEmitter {
       }
       if (!this.stopRequested) {
         if (!didBlock) {
-          await new Promise((resolve) => setTimeout(resolve, currentPollInterval));
+          await new Promise((resolve2) => setTimeout(resolve2, currentPollInterval));
           currentPollInterval = Math.min(currentPollInterval * backoffMultiplier, maxPollInterval);
         }
       } else {
-        await new Promise((resolve) => setTimeout(resolve, 50));
+        await new Promise((resolve2) => setTimeout(resolve2, 50));
       }
     }
     this.running = false;
     this.stopHeartbeat();
+    this.stopCleanupTimer();
     if (this.options.monitor) {
       await this.publishLog("info", "Consumer stopped");
     }
     this.log("Stopped");
   }
   /**
-   * Run a job with concurrency controls.
+   * Run a job with concurrency controls and group locking.
    */
   async runJob(job, worker) {
     if (!job.groupId || this.options.groupJobsSequential === false) {
@@ -3750,6 +5060,7 @@ var Consumer = class extends import_node_events.EventEmitter {
       limiter = (0, import_p_limit.default)(1);
       this.groupLimiters.set(job.groupId, limiter);
     }
+    this.groupLimiterLastUsed.set(job.groupId, Date.now());
     if (limiter.pendingCount > 0) {
       this.log(`Job ${job.id} queued behind group ${job.groupId}`);
     }
@@ -3758,16 +5069,18 @@ var Consumer = class extends import_node_events.EventEmitter {
     });
     if (limiter.activeCount === 0 && limiter.pendingCount === 0) {
       this.groupLimiters.delete(job.groupId);
+      this.groupLimiterLastUsed.delete(job.groupId);
     }
   }
   /**
-   * Handle a single job.
+   * Delegates the actual processing to the worker and handles stats/logging.
    */
   async handleJob(job, worker) {
     const currentQueue = job.queueName || "default";
     const startTime = Date.now();
     this.log(`Processing job ${job.id} from ${currentQueue}`);
     this.emit("job:started", { job, queue: currentQueue });
+    this.options.onEvent?.("job:started", { jobId: job.id, queue: currentQueue });
     if (this.options.monitor) {
       await this.publishLog("info", `Processing job: ${job.id}`, job.id);
     }
@@ -3776,14 +5089,32 @@ var Consumer = class extends import_node_events.EventEmitter {
       const duration = Date.now() - startTime;
       this.stats.processed++;
       this.emit("job:processed", { job, duration, queue: currentQueue });
+      this.options.onEvent?.("job:processed", { jobId: job.id, duration, queue: currentQueue });
       this.log(`Completed job ${job.id} in ${duration}ms`);
       if (this.options.monitor) {
         await this.publishLog("success", `Completed job: ${job.id}`, job.id);
       }
+      if (this.options.maxRequests && this.stats.processed >= this.options.maxRequests) {
+        this.log(`Max requests reached: ${this.stats.processed}/${this.options.maxRequests}`);
+        this.stopRequested = true;
+        this.emit("max_requests_reached", {
+          processed: this.stats.processed,
+          maxRequests: this.options.maxRequests
+        });
+        if (this.options.monitor) {
+          await this.publishLog("info", `Max requests reached: ${this.stats.processed}`, job.id);
+        }
+      }
     } catch (err) {
       const error = err;
       const duration = Date.now() - startTime;
       this.emit("job:failed", { job, error, duration, queue: currentQueue });
+      this.options.onEvent?.("job:failed", {
+        jobId: job.id,
+        error: error.message,
+        duration,
+        queue: currentQueue
+      });
       this.log(`Failed job ${job.id} in ${duration}ms`, { error: error.message });
       this.stats.failed++;
       if (this.options.monitor) {
@@ -3809,6 +5140,7 @@ var Consumer = class extends import_node_events.EventEmitter {
         }
       } else {
         this.emit("job:failed_permanently", { job, error });
+        this.options.onEvent?.("job:failed_permanently", { jobId: job.id, error: error.message });
         this.log(`Job ${job.id} failed permanently`);
         await this.queueManager.fail(job, error).catch((dlqErr) => {
           console.error("[Consumer] Error moving job to DLQ:", dlqErr);
@@ -3866,6 +5198,48 @@ var Consumer = class extends import_node_events.EventEmitter {
       this.heartbeatTimer = null;
     }
   }
+  /**
+   * 清理閒置的 group limiters。
+   *
+   * 定期檢查並移除超過 TTL 且沒有 active/pending jobs 的 group limiters，
+   * 避免記憶體洩漏。
+   */
+  cleanupGroupLimiters() {
+    const now = Date.now();
+    const groupsToDelete = [];
+    for (const [groupId, lastUsed] of this.groupLimiterLastUsed.entries()) {
+      const limiter = this.groupLimiters.get(groupId);
+      if (!limiter) {
+        groupsToDelete.push(groupId);
+        continue;
+      }
+      if (now - lastUsed > _Consumer.GROUP_LIMITER_TTL && limiter.activeCount === 0 && limiter.pendingCount === 0) {
+        this.groupLimiters.delete(groupId);
+        groupsToDelete.push(groupId);
+        this.log(`Cleaned up inactive group limiter: ${groupId}`);
+      }
+    }
+    for (const groupId of groupsToDelete) {
+      this.groupLimiterLastUsed.delete(groupId);
+    }
+  }
+  /**
+   * 啟動 group limiter 清理計時器。
+   */
+  startCleanupTimer() {
+    this.cleanupTimer = setInterval(() => {
+      this.cleanupGroupLimiters();
+    }, 3e4);
+  }
+  /**
+   * 停止 group limiter 清理計時器。
+   */
+  stopCleanupTimer() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
   async publishLog(level, message, jobId) {
     try {
       const driver = this.queueManager.getDriver(this.connectionName);
@@ -3886,29 +5260,39 @@ var Consumer = class extends import_node_events.EventEmitter {
     }
   }
   /**
-   * Stop the consumer loop (graceful shutdown).
+   * 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.
    */
   async stop() {
     this.log("Stopping...");
     this.stopRequested = true;
+    this.stopCleanupTimer();
     while (this.running) {
-      await new Promise((resolve) => setTimeout(resolve, 100));
+      await new Promise((resolve2) => setTimeout(resolve2, 100));
     }
   }
   /**
-   * Check whether the consumer is running.
+   * Checks if the consumer is currently active.
+   *
+   * @returns True if the consumer loop is running.
    */
   isRunning() {
     return this.running;
   }
   /**
-   * Get current consumer statistics.
+   * Retrieves current operational statistics.
+   *
+   * @returns An object containing processed, failed, retried, and active job counts.
    */
   getStats() {
     return { ...this.stats };
   }
   /**
-   * Reset statistics counters.
+   * Resets the internal statistics counters.
    */
   resetStats() {
     this.stats.processed = 0;
@@ -3918,7 +5302,165 @@ var Consumer = class extends import_node_events.EventEmitter {
 };
 
 // src/index.ts
+init_BullMQDriver();
 init_DatabaseDriver();
+
+// src/drivers/GrpcDriver.ts
+var import_node_path2 = __toESM(require("path"), 1);
+var grpc = __toESM(require("@grpc/grpc-js"), 1);
+var protoLoader = __toESM(require("@grpc/proto-loader"), 1);
+var GrpcDriver = class {
+  client;
+  constructor(config) {
+    const protoPath = config.protoPath || import_node_path2.default.resolve(__dirname, "../../proto/queue.proto");
+    const packageDefinition = protoLoader.loadSync(protoPath, {
+      keepCase: true,
+      longs: String,
+      enums: String,
+      defaults: true,
+      oneofs: true
+    });
+    const packageName = config.packageName || "stream";
+    const serviceName = config.serviceName || "QueueService";
+    const pkg = packageDefinition[packageName];
+    if (!pkg) {
+      throw new Error(`Package '${packageName}' not found in proto definition at ${protoPath}`);
+    }
+    const Service = pkg[serviceName];
+    if (!Service) {
+      throw new Error(`Service '${serviceName}' not found in package '${packageName}'`);
+    }
+    const credentials2 = this.getCredentials(config);
+    this.client = new Service(config.url, credentials2);
+  }
+  getCredentials(config) {
+    if (config.credentials) {
+      if (config.credentials.rootCerts) {
+        return grpc.credentials.createSsl(
+          config.credentials.rootCerts,
+          config.credentials.privateKey,
+          config.credentials.certChain
+        );
+      }
+    }
+    return grpc.credentials.createInsecure();
+  }
+  async push(queue, job, options) {
+    const req = {
+      queue,
+      job: this.toProtoJob(job),
+      options: {
+        groupId: options?.groupId,
+        priority: String(options?.priority || "")
+      }
+    };
+    return new Promise((resolve2, reject) => {
+      ;
+      this.client.Push(req, (err, response) => {
+        if (err) {
+          return reject(err);
+        }
+        if (!response.success) {
+          return reject(new Error(response.message || "Unknown gRPC error"));
+        }
+        resolve2();
+      });
+    });
+  }
+  async pop(queue) {
+    return new Promise((resolve2, reject) => {
+      ;
+      this.client.Pull({ queue }, (err, response) => {
+        if (err) {
+          return reject(err);
+        }
+        if (!response.job || !response.job.id) {
+          return resolve2(null);
+        }
+        resolve2(this.fromProtoJob(response.job));
+      });
+    });
+  }
+  async size(queue) {
+    return new Promise((resolve2, reject) => {
+      ;
+      this.client.Size({ queue }, (err, response) => {
+        if (err) {
+          return reject(err);
+        }
+        resolve2(response.size || 0);
+      });
+    });
+  }
+  async clear(queue) {
+    return new Promise((resolve2, reject) => {
+      ;
+      this.client.Clear({ queue }, (err) => {
+        if (err) {
+          return reject(err);
+        }
+        resolve2();
+      });
+    });
+  }
+  async acknowledge(messageId) {
+    return new Promise((resolve2, reject) => {
+      ;
+      this.client.Acknowledge({ jobId: messageId }, (err) => {
+        if (err) {
+          return reject(err);
+        }
+        resolve2();
+      });
+    });
+  }
+  async stats(queue) {
+    return new Promise((resolve2, reject) => {
+      ;
+      this.client.Stats({ queue }, (err, response) => {
+        if (err) {
+          return reject(err);
+        }
+        resolve2({
+          queue: response.queue,
+          size: response.size,
+          delayed: response.delayed,
+          failed: response.failed,
+          reserved: response.reserved
+        });
+      });
+    });
+  }
+  toProtoJob(job) {
+    return {
+      ...job,
+      priority: job.priority ? String(job.priority) : void 0,
+      createdAt: String(job.createdAt),
+      // Long as string
+      failedAt: job.failedAt ? String(job.failedAt) : void 0
+    };
+  }
+  fromProtoJob(protoJob) {
+    return {
+      id: protoJob.id,
+      type: protoJob.type,
+      data: protoJob.data,
+      className: protoJob.className,
+      createdAt: Number(protoJob.createdAt),
+      delaySeconds: protoJob.delaySeconds,
+      attempts: protoJob.attempts,
+      maxAttempts: protoJob.maxAttempts,
+      groupId: protoJob.groupId,
+      priority: protoJob.priority,
+      failedAt: protoJob.failedAt ? Number(protoJob.failedAt) : void 0,
+      error: protoJob.error,
+      retryAfterSeconds: protoJob.retryAfterSeconds,
+      retryMultiplier: protoJob.retryMultiplier
+    };
+  }
+};
+
+// src/index.ts
 init_KafkaDriver();
 
 // src/drivers/MemoryDriver.ts
@@ -3929,7 +5471,11 @@ var MemoryDriver = class {
     this.maxSize = config.maxSize ?? Infinity;
   }
   /**
-   * 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`.
    */
   async push(queue, job) {
     if (!this.queues.has(queue)) {
@@ -3942,7 +5488,12 @@ var MemoryDriver = class {
     q.push(job);
   }
   /**
-   * 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`.
    */
   async pop(queue) {
     const queueJobs = this.queues.get(queue);
@@ -3959,19 +5510,28 @@ var MemoryDriver = class {
     return queueJobs.splice(availableIndex, 1)[0];
   }
   /**
-   * Get queue size.
+   * Returns the number of jobs in the queue.
+   *
+   * @param queue - The queue name.
    */
   async size(queue) {
     return this.queues.get(queue)?.length ?? 0;
   }
   /**
-   * Clear a queue.
+   * Clears all jobs from the queue.
+   *
+   * @param queue - The queue name.
    */
   async clear(queue) {
     this.queues.delete(queue);
   }
   /**
-   * 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.
    */
   async fail(queue, job) {
     const failedQueue = `failed:${queue}`;
@@ -3981,7 +5541,11 @@ var MemoryDriver = class {
     this.queues.get(failedQueue)?.push(job);
   }
   /**
-   * Get queue statistics.
+   * Retrieves statistics for the queue.
+   *
+   * Calculates pending, delayed, and failed counts by iterating through the list.
+   *
+   * @param queue - The queue name.
    */
   async stats(queue) {
     const jobs = this.queues.get(queue) || [];
@@ -4004,7 +5568,10 @@ var MemoryDriver = class {
     };
   }
   /**
-   * Push multiple jobs.
+   * Pushes multiple jobs to the queue.
+   *
+   * @param queue - The queue name.
+   * @param jobs - Array of jobs.
    */
   async pushMany(queue, jobs) {
     if (!this.queues.has(queue)) {
@@ -4013,7 +5580,10 @@ var MemoryDriver = class {
     this.queues.get(queue)?.push(...jobs);
   }
   /**
-   * Pop multiple jobs.
+   * Pops multiple jobs from the queue.
+   *
+   * @param queue - The queue name.
+   * @param count - Max jobs to pop.
    */
   async popMany(queue, count) {
     const results = [];
@@ -4027,6 +5597,12 @@ var MemoryDriver = class {
     }
     return results;
   }
+  /**
+   * Lists all active queues in memory.
+   */
+  async getQueues() {
+    return Array.from(this.queues.keys()).filter((q) => !q.startsWith("failed:")).sort();
+  }
 };
 
 // src/index.ts
@@ -4037,78 +5613,128 @@ init_SQSDriver();
 // src/Job.ts
 var Job = class {
   /**
-   * Unique job identifier.
+   * Unique identifier for the job instance.
+   *
+   * Assigned automatically when the job is pushed to the queue.
    */
   id;
   /**
-   * Queue name.
+   * The name of the queue where this job will be processed.
    */
   queueName;
   /**
-   * Connection name.
+   * The name of the connection used to transport this job.
    */
   connectionName;
   /**
-   * Delay before execution (seconds).
+   * Delay in seconds before the job becomes available for processing.
    */
   delaySeconds;
   /**
-   * Current attempt number.
+   * The current attempt number (starts at 1).
    */
   attempts;
   /**
-   * Maximum attempts.
+   * The maximum number of retry attempts allowed.
+   *
+   * Can be overridden by the worker configuration or per-job using `maxAttempts`.
    */
   maxAttempts;
   /**
-   * Group ID for FIFO.
+   * Group ID for sequential processing.
+   *
+   * Jobs with the same `groupId` will be processed in strict order (FIFO)
+   * if the consumer supports it.
    */
   groupId;
   /**
-   * Job priority.
+   * Priority level of the job.
    */
   priority;
   /**
-   * Initial retry delay (seconds).
+   * Initial delay in seconds before the first retry attempt.
+   *
+   * Used for exponential backoff calculation.
    */
   retryAfterSeconds;
   /**
-   * Retry delay multiplier.
+   * Multiplier applied to the retry delay for each subsequent attempt.
+   *
+   * Used for exponential backoff calculation.
    */
   retryMultiplier;
   /**
-   * Set target queue.
+   * 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) {
     this.queueName = queue;
     return this;
   }
   /**
-   * Set target connection.
+   * 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) {
     this.connectionName = connection;
     return this;
   }
   /**
-   * Set job priority.
-   * @param priority - 'high', 'low', or number
+   * 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) {
     this.priority = priority;
     return this;
   }
   /**
-   * Set delay (seconds).
+   * 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) {
     this.delaySeconds = delay;
     return this;
   }
   /**
-   * Set retry backoff strategy.
-   * @param seconds - Initial delay in seconds
-   * @param multiplier - Multiplier for each subsequent attempt (default: 2)
+   * 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, multiplier = 2) {
     this.retryAfterSeconds = seconds;
@@ -4116,9 +5742,17 @@ var Job = class {
     return this;
   }
   /**
-   * Calculate retry delay for the next attempt.
-   * @param attempt - Current attempt number (1-based)
-   * @returns Delay in milliseconds
+   * 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) {
     const initialDelay = (this.retryAfterSeconds ?? 1) * 1e3;
@@ -4126,28 +5760,40 @@ var Job = class {
     return Math.min(initialDelay * multiplier ** (attempt - 1), 36e5);
   }
   /**
-   * Failure handler (optional).
+   * 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.
    *
-   * Called when the job fails and reaches the maximum number of attempts.
-   * Subclasses can override to implement custom failure handling.
+   * @param _error - The error that caused the final failure.
    *
-   * @param error - Error instance
+   * @example
+   * ```typescript
+   * async failed(error: Error) {
+   *   await notifyAdmin(`Job failed: ${error.message}`);
+   * }
+   * ```
    */
   async failed(_error) {
   }
 };
 
+// src/index.ts
+init_DistributedLock();
+
 // src/serializers/CachedSerializer.ts
 var CachedSerializer = class {
   /**
-   * @param delegate - The actual serializer to use for the first serialization
+   * @param delegate - The underlying serializer to use.
    */
   constructor(delegate) {
     this.delegate = delegate;
   }
   cache = /* @__PURE__ */ new WeakMap();
   /**
-   * Serialize a job with caching.
+   * Serializes the job, returning a cached result if available.
+   *
+   * @param job - The job to serialize.
    */
   serialize(job) {
     if (this.cache.has(job)) {
@@ -4158,8 +5804,9 @@ var CachedSerializer = class {
     return serialized;
   }
   /**
-   * Deserialize a job.
-   * No caching for deserialization as we get new objects each time from the driver.
+   * Deserializes a job.
+   *
+   * Caching is not applied here as deserialization always produces new instances.
    */
   deserialize(serialized) {
     return this.delegate.deserialize(serialized);
@@ -4169,19 +5816,21 @@ var CachedSerializer = class {
 // src/serializers/ClassNameSerializer.ts
 var ClassNameSerializer = class {
   /**
-   * Job class registry (for resolving classes by name).
+   * Registry of job classes, mapped by class name.
    */
   jobClasses = /* @__PURE__ */ new Map();
   /**
-   * Register a Job class.
-   * @param jobClass - Job class
+   * Registers a Job class for serialization.
+   *
+   * @param jobClass - The job class constructor.
    */
   register(jobClass) {
     this.jobClasses.set(jobClass.name, jobClass);
   }
   /**
-   * 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) {
     for (const jobClass of jobClasses) {
@@ -4189,7 +5838,11 @@ var ClassNameSerializer = class {
     }
   }
   /**
-   * Serialize a Job.
+   * Serializes a Job instance.
+   *
+   * Captures the class name and all enumerable properties.
+   *
+   * @param job - The job to serialize.
    */
   serialize(job) {
     const id = job.id || `${Date.now()}-${crypto.randomUUID()}`;
@@ -4216,7 +5869,12 @@ var ClassNameSerializer = class {
     };
   }
   /**
-   * 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) {
     if (serialized.type !== "class") {
@@ -4265,7 +5923,7 @@ var ClassNameSerializer = class {
 // src/serializers/JsonSerializer.ts
 var JsonSerializer = class {
   /**
-   * Serialize a job.
+   * Serializes a job to a JSON object.
    */
   serialize(job) {
     const id = job.id || `${Date.now()}-${crypto.randomUUID()}`;
@@ -4288,7 +5946,9 @@ var JsonSerializer = class {
     };
   }
   /**
-   * 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) {
     if (serialized.type !== "json") {
@@ -4370,9 +6030,18 @@ var QueueManager = class {
     }
   }
   /**
-   * 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, config) {
     const driverType = config.driver;
@@ -4463,16 +6132,41 @@ var QueueManager = class {
         );
         break;
       }
+      case "bullmq": {
+        const { BullMQDriver: BullMQDriver2 } = (init_BullMQDriver(), __toCommonJS(BullMQDriver_exports));
+        if (!config.queue) {
+          throw new Error(
+            "[QueueManager] BullMQDriver requires queue. Please provide Bull Queue instance in connection config."
+          );
+        }
+        this.drivers.set(
+          name,
+          new BullMQDriver2({
+            queue: config.queue,
+            worker: config.worker,
+            prefix: config.prefix,
+            debug: config.debug
+          })
+        );
+        break;
+      }
       default:
         throw new Error(
-          `Driver "${driverType}" is not supported. Supported drivers: memory, database, redis, kafka, sqs, rabbitmq`
+          `Driver "${driverType}" is not supported. Supported drivers: memory, database, redis, kafka, sqs, rabbitmq, bullmq`
         );
     }
   }
   /**
-   * 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) {
     const driver = this.drivers.get(connection);
@@ -4482,16 +6176,19 @@ var QueueManager = class {
     return driver;
   }
   /**
-   * Get the default connection name.
-   * @returns Default connection name
+   * Gets the name of the default connection.
+   *
+   * @returns The default connection name.
    */
   getDefaultConnection() {
     return this.defaultConnection;
   }
   /**
-   * 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) {
     if (type) {
@@ -4504,8 +6201,17 @@ var QueueManager = class {
     return this.defaultSerializer;
   }
   /**
-   * 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) {
     if (this.defaultSerializer instanceof ClassNameSerializer) {
@@ -4513,12 +6219,15 @@ var QueueManager = class {
     }
   }
   /**
-   * Push a Job to the queue.
+   * 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.
-   * @param job - Job instance to push.
-   * @param options - Push options.
-   * @returns The same job instance (for fluent chaining).
+   * @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
@@ -4549,15 +6258,19 @@ var QueueManager = class {
     return job;
   }
   /**
-   * Push multiple jobs to the queue.
+   * 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 - Array of job instances.
-   * @param options - Bulk push options.
+   * @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: 2 });
+   * await manager.pushMany(jobs, { batchSize: 500, concurrency: 5 });
    * ```
    */
   async pushMany(jobs, options = {}) {
@@ -4619,15 +6332,17 @@ var QueueManager = class {
     }
   }
   /**
-   * Pop a job from the queue.
+   * Pops a single job from the queue.
    *
-   * @param queue - Queue name (default: 'default').
-   * @param connection - Connection name (optional).
-   * @returns Job instance or null if queue is empty.
+   * 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('emails');
+   * const job = await manager.pop('priority-queue');
    * if (job) await job.handle();
    * ```
    */
@@ -4647,12 +6362,20 @@ var QueueManager = class {
     }
   }
   /**
-   * Pop multiple jobs from the queue.
+   * 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.
    *
-   * @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.
+   * @example
+   * ```typescript
+   * const jobs = await manager.popMany('default', 50);
+   * ```
    */
   async popMany(queue = "default", count = 10, connection = this.defaultConnection) {
     const driver = this.getDriver(connection);
@@ -4683,22 +6406,37 @@ var QueueManager = class {
     return results;
   }
   /**
-   * Get queue size.
+   * Retrieves the current size of a queue.
    *
-   * @param queue - Queue name (default: 'default').
-   * @param connection - Connection name (optional).
-   * @returns Number of jobs in the 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');
+   * ```
    */
   async size(queue = "default", connection = this.defaultConnection) {
     const driver = this.getDriver(connection);
     return driver.size(queue);
   }
   /**
-   * Pop a job from the queue (blocking).
+   * 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 queue - Queue name (default: 'default').
-   * @param timeout - Timeout in seconds (default: 0, wait forever).
-   * @param connection - Connection name (optional).
+   * @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);
+   * ```
    */
   async popBlocking(queues = "default", timeout = 0, connection = this.defaultConnection) {
     const driver = this.getDriver(connection);
@@ -4723,21 +6461,34 @@ var QueueManager = class {
     }
   }
   /**
-   * Clear all jobs from a queue.
+   * Removes all jobs from a specific queue.
+   *
+   * @param queue - The queue name to purge.
+   * @param connection - The connection name.
    *
-   * @param queue - Queue name (default: 'default').
-   * @param connection - Connection name (optional).
+   * @example
+   * ```typescript
+   * await manager.clear('test-queue');
+   * ```
    */
   async clear(queue = "default", connection = this.defaultConnection) {
     const driver = this.getDriver(connection);
     await driver.clear(queue);
   }
   /**
-   * Get queue statistics including size, delayed, and failed job counts.
+   * Retrieves comprehensive statistics for a queue.
    *
-   * @param queue - Queue name (default: 'default').
-   * @param connection - Connection name (optional).
-   * @returns Queue statistics object.
+   * 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);
+   * ```
    */
   async stats(queue = "default", connection = this.defaultConnection) {
     const driver = this.getDriver(connection);
@@ -4750,8 +6501,16 @@ var QueueManager = class {
     };
   }
   /**
-   * Mark a job as completed.
-   * @param job - Job instance
+   * 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);
+   * ```
    */
   async complete(job) {
     const connection = job.connectionName ?? this.defaultConnection;
@@ -4770,9 +6529,18 @@ var QueueManager = class {
     }
   }
   /**
-   * Mark a job as permanently failed.
-   * @param job - Job instance
-   * @param error - Error object
+   * 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'));
+   * ```
    */
   async fail(job, error) {
     const connection = job.connectionName ?? this.defaultConnection;
@@ -4793,13 +6561,19 @@ var QueueManager = class {
     }
   }
   /**
-   * Get the persistence adapter if configured.
+   * Retrieves the configured persistence adapter.
+   *
+   * @returns The PersistenceAdapter instance, or undefined if not configured.
    */
   getPersistence() {
     return this.persistence?.adapter;
   }
   /**
-   * Get the scheduler if configured.
+   * Gets the Scheduler instance associated with this manager.
+   *
+   * The Scheduler handles delayed jobs and periodic tasks.
+   *
+   * @returns The Scheduler instance.
    */
   getScheduler() {
     if (!this.scheduler) {
@@ -4809,7 +6583,18 @@ var QueueManager = class {
     return this.scheduler;
   }
   /**
-   * Get failed jobs from DLQ (if driver supports it).
+   * 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);
+   * ```
    */
   async getFailed(queue, start = 0, end = -1, connection = this.defaultConnection) {
     const driver = this.getDriver(connection);
@@ -4819,7 +6604,19 @@ var QueueManager = class {
     return [];
   }
   /**
-   * Retry failed jobs from DLQ (if driver supports it).
+   * 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);
+   * ```
    */
   async retryFailed(queue, count = 1, connection = this.defaultConnection) {
     const driver = this.getDriver(connection);
@@ -4829,7 +6626,15 @@ var QueueManager = class {
     return 0;
   }
   /**
-   * Clear failed jobs from DLQ (if driver supports it).
+   * 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');
+   * ```
    */
   async clearFailed(queue, connection = this.defaultConnection) {
     const driver = this.getDriver(connection);
@@ -4837,6 +6642,219 @@ var QueueManager = class {
       await driver.clearFailed(queue);
     }
   }
+  /**
+   * 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.
+   */
+  async getGlobalStats() {
+    const stats = {
+      connections: {},
+      totalSize: 0,
+      totalFailed: 0,
+      timestamp: Date.now()
+    };
+    for (const [name, driver] of this.drivers.entries()) {
+      const queueNames = driver.getQueues ? await driver.getQueues() : ["default"];
+      const connectionStats = [];
+      for (const queue of queueNames) {
+        const qStats = await this.stats(queue, name);
+        connectionStats.push(qStats);
+        stats.totalSize += qStats.size;
+        stats.totalFailed += qStats.failed ?? 0;
+      }
+      stats.connections[name] = connectionStats;
+    }
+    return stats;
+  }
+};
+
+// src/SystemEventJob.ts
+var import_core = require("@gravito/core");
+var SystemEventJob = class extends Job {
+  constructor(hook, args, options = {}) {
+    super();
+    this.hook = hook;
+    this.args = args;
+    this.options = options;
+    if (options.queue) {
+      this.onQueue(options.queue);
+    }
+    if (options.priority) {
+      this.withPriority(options.priority);
+    }
+    if (options.delay) {
+      this.delay(options.delay);
+    }
+    if (options.retryAfter) {
+      this.backoff(options.retryAfter, options.retryMultiplier);
+    }
+    if (options.connection) {
+      this.onConnection(options.connection);
+    }
+  }
+  /**
+   * Optional failure callback for DLQ handling.
+   */
+  onFailedCallback;
+  /**
+   * Set failure callback for DLQ handling.
+   *
+   * @param callback - Called when job fails permanently
+   * @returns Self for chaining
+   */
+  onFailed(callback) {
+    this.onFailedCallback = callback;
+    return this;
+  }
+  /**
+   * Execute the hook listeners in the worker process.
+   */
+  async handle() {
+    const core = (0, import_core.app)();
+    if (core?.hooks) {
+      await core.hooks.doActionSync(this.hook, this.args);
+    }
+  }
+  /**
+   * Called when job fails permanently after all retries.
+   *
+   * This method is invoked by the worker when job exhausts all retry attempts.
+   */
+  async failed(error, attempt = 1) {
+    if (this.onFailedCallback) {
+      try {
+        await this.onFailedCallback(error, attempt);
+      } catch (callbackError) {
+        console.error("[SystemEventJob] Failed callback error:", callbackError);
+      }
+    }
+  }
+};
+
+// src/StreamEventBackend.ts
+var StreamEventBackend = class {
+  constructor(queueManager, config) {
+    this.queueManager = queueManager;
+    this.config = {
+      retryStrategy: "bull",
+      circuitBreakerIntegration: false,
+      ...config
+    };
+  }
+  config;
+  /**
+   * Build Job Push Options from EventOptions.
+   *
+   * Maps EventOptions to Bull Queue JobPushOptions with retry strategy applied.
+   */
+  buildJobOptions(task) {
+    const options = {};
+    if (task.options?.priority) {
+      options.priority = task.options.priority;
+    }
+    const taskOptionsAny = task.options;
+    if (taskOptionsAny?.groupId) {
+      options.groupId = taskOptionsAny.groupId;
+    }
+    return options;
+  }
+  /**
+   * Enqueue an event task to the stream queue.
+   *
+   * Applies retry strategy and CircuitBreaker checks based on configuration.
+   * Supports DLQ routing for failed events.
+   */
+  async enqueue(task) {
+    if (this.config.circuitBreakerIntegration && this.config.getCircuitBreaker) {
+      const breaker = this.config.getCircuitBreaker(task.hook);
+      if (breaker?.getState?.() === "OPEN") {
+        throw new Error(`Circuit breaker OPEN for event: ${task.hook}`);
+      }
+    }
+    const job = new SystemEventJob(task.hook, task.args, task.options);
+    this.applyRetryStrategy(job, task);
+    if (this.config.dlqHandler) {
+      job.onFailed(async (error, attempt) => {
+        await this.handleJobFailure(task, error, attempt);
+      });
+    }
+    const options = this.buildJobOptions(task);
+    await this.queueManager.push(job, options);
+  }
+  /**
+   * Apply retry strategy to the job based on configuration.
+   */
+  applyRetryStrategy(job, task) {
+    const strategy = this.config.retryStrategy ?? "bull";
+    const taskOptionsAny = task.options;
+    if (strategy === "bull" || strategy === "hybrid") {
+      job.maxAttempts = taskOptionsAny?.maxAttempts ?? 3;
+      job.retryAfterSeconds = taskOptionsAny?.retryAfter ?? 5;
+      job.retryMultiplier = taskOptionsAny?.retryMultiplier ?? 2;
+    }
+  }
+  /**
+   * Handle job failure and route to DLQ if configured.
+   *
+   * Called when a job exhausts all retry attempts.
+   */
+  async handleJobFailure(task, error, attempt) {
+    if (this.config.dlqHandler) {
+      try {
+        await this.config.dlqHandler.handle(task, error, attempt);
+      } catch (dlqError) {
+        console.error("[StreamEventBackend] Failed to handle DLQ:", dlqError);
+      }
+    }
+  }
+  /**
+   * Record a job failure for CircuitBreaker state management.
+   *
+   * Called when a job fails, regardless of retry status.
+   */
+  recordJobFailure(task, error) {
+    if (this.config.circuitBreakerIntegration && this.config.getCircuitBreaker) {
+      const breaker = this.config.getCircuitBreaker(task.hook);
+      if (breaker?.recordFailure) {
+        breaker.recordFailure(error);
+      }
+    }
+  }
+  /**
+   * Record a job success for CircuitBreaker state management.
+   *
+   * Called when a job completes successfully.
+   */
+  recordJobSuccess(task) {
+    if (this.config.circuitBreakerIntegration && this.config.getCircuitBreaker) {
+      const breaker = this.config.getCircuitBreaker(task.hook);
+      if (breaker?.recordSuccess) {
+        breaker.recordSuccess();
+      }
+    }
+  }
+  /**
+   * Get the retry strategy configuration.
+   */
+  getRetryStrategy() {
+    return this.config.retryStrategy ?? "bull";
+  }
+  /**
+   * Check if CircuitBreaker integration is enabled.
+   */
+  isCircuitBreakerEnabled() {
+    return this.config.circuitBreakerIntegration ?? false;
+  }
+  /**
+   * Get the DLQ handler, if configured.
+   */
+  getDLQHandler() {
+    return this.config.dlqHandler;
+  }
 };
 
 // src/OrbitStream.ts
@@ -4846,16 +6864,37 @@ var OrbitStream = class _OrbitStream {
   }
   queueManager;
   consumer;
+  core;
   /**
-   * 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) {
     return new _OrbitStream(options);
   }
   /**
-   * 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) {
+    this.core = core;
     this.queueManager = new QueueManager(this.options);
     core.container.instance("queue", this.queueManager);
     core.adapter.use("*", async (c, next) => {
@@ -4883,12 +6922,35 @@ var OrbitStream = class _OrbitStream {
       return await next();
     });
     core.logger.info("[OrbitStream] Installed");
+    if (this.queueManager) {
+      const backend = new StreamEventBackend(this.queueManager);
+      core.hooks.setBackend(backend);
+      core.logger.info("[OrbitStream] HookManager backend switched to StreamEventBackend");
+    }
+    if (this.options.dashboard) {
+      const { DashboardProvider: DashboardProvider2 } = (init_DashboardProvider(), __toCommonJS(DashboardProvider_exports));
+      const dashboard = new DashboardProvider2(this.queueManager);
+      const path2 = typeof this.options.dashboard === "object" ? this.options.dashboard.path : "/_flux";
+      dashboard.registerRoutes(core, path2);
+      core.logger.info(`[OrbitStream] Dashboard API registered at ${path2}`);
+    }
     if (this.options.autoStartWorker && process.env.NODE_ENV === "development" && this.options.workerOptions) {
       this.startWorker(this.options.workerOptions);
     }
   }
   /**
-   * 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) {
     if (!this.queueManager) {
@@ -4897,13 +6959,31 @@ var OrbitStream = class _OrbitStream {
     if (this.consumer?.isRunning()) {
       throw new Error("Worker is already running");
     }
-    this.consumer = new Consumer(this.queueManager, options);
+    const consumerOptions = {
+      ...options,
+      onEvent: (event, payload) => {
+        const signal = this.core?.container.make("signal");
+        if (signal && typeof signal.emit === "function") {
+          signal.emit(`stream:${event}`, payload);
+        }
+      }
+    };
+    this.consumer = new Consumer(this.queueManager, consumerOptions);
     this.consumer.start().catch((error) => {
       console.error("[OrbitStream] Worker error:", error);
     });
   }
   /**
-   * 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();
+   * ```
    */
   async stopWorker() {
     if (this.consumer) {
@@ -4911,7 +6991,14 @@ var OrbitStream = class _OrbitStream {
     }
   }
   /**
-   * Get QueueManager instance.
+   * Retrieves the underlying QueueManager instance.
+   *
+   * @returns The active QueueManager, or undefined if not installed.
+   *
+   * @example
+   * ```typescript
+   * const manager = orbit.getQueueManager();
+   * ```
    */
   getQueueManager() {
     return this.queueManager;
@@ -4935,9 +7022,15 @@ var MySQLPersistence = class {
     this.table = table;
     this.logsTable = logsTable;
   }
+  /**
+   * Archives a single job.
+   */
   async archive(queue, job, status) {
     await this.archiveMany([{ queue, job, status }]);
   }
+  /**
+   * Archives multiple jobs in a batch.
+   */
   async archiveMany(jobs) {
     if (jobs.length === 0) {
       return;
@@ -4961,8 +7054,14 @@ var MySQLPersistence = class {
       }
     }
   }
+  /**
+   * No-op. Use BufferedPersistence if flushing is needed.
+   */
   async flush() {
   }
+  /**
+   * Finds an archived job by ID.
+   */
   async find(queue, id) {
     const row = await this.db.table(this.table).where("queue", queue).where("job_id", id).first();
     if (!row) {
@@ -5006,6 +7105,9 @@ var MySQLPersistence = class {
   }
   /**
    * Search jobs from the archive.
+   *
+   * @param query - Search string (matches ID, payload, or error).
+   * @param options - Filter options.
    */
   async search(query, options = {}) {
     let q = this.db.table(this.table);
@@ -5027,13 +7129,13 @@ var MySQLPersistence = class {
     );
   }
   /**
-   * Archive a system log message (buffered).
+   * Archive a system log message.
    */
   async archiveLog(log) {
     await this.archiveLogMany([log]);
   }
   /**
-   * Archive multiple log messages (direct batch write).
+   * Archive multiple log messages.
    */
   async archiveLogMany(logs) {
     if (logs.length === 0) {
@@ -5137,7 +7239,7 @@ var MySQLPersistence = class {
     return Number(result) || 0;
   }
   /**
-   * Help script to create the necessary table.
+   * Helper to create necessary tables if they don't exist.
    */
   async setupTable() {
     await Promise.all([this.setupJobsTable(), this.setupLogsTable()]);
@@ -5198,9 +7300,17 @@ var SQLitePersistence = class {
     this.table = table;
     this.logsTable = logsTable;
   }
+  /**
+   * Archives a single job.
+   */
   async archive(queue, job, status) {
     await this.archiveMany([{ queue, job, status }]);
   }
+  /**
+   * Archives multiple jobs in a batch.
+   *
+   * Optimized for SQLite by wrapping chunks in transactions.
+   */
   async archiveMany(jobs) {
     if (jobs.length === 0) {
       return;
@@ -5231,8 +7341,14 @@ var SQLitePersistence = class {
       }
     }
   }
+  /**
+   * No-op. Use BufferedPersistence if flushing is needed.
+   */
   async flush() {
   }
+  /**
+   * Finds an archived job by ID.
+   */
   async find(queue, id) {
     const row = await this.db.table(this.table).where("queue", queue).where("job_id", id).first();
     if (!row) {
@@ -5251,7 +7367,11 @@ var SQLitePersistence = class {
   async list(queue, options = {}) {
     let query = this.db.table(this.table).where("queue", queue);
     if (options.status) {
-      query = query.where("status", options.status);
+      if (Array.isArray(options.status)) {
+        query = query.whereIn("status", options.status);
+      } else {
+        query = query.where("status", options.status);
+      }
     }
     if (options.jobId) {
       query = query.where("job_id", options.jobId);
@@ -5392,7 +7512,11 @@ var SQLitePersistence = class {
   async count(queue, options = {}) {
     let query = this.db.table(this.table).where("queue", queue);
     if (options.status) {
-      query = query.where("status", options.status);
+      if (Array.isArray(options.status)) {
+        query = query.whereIn("status", options.status);
+      } else {
+        query = query.where("status", options.status);
+      }
     }
     if (options.jobId) {
       query = query.where("job_id", options.jobId);
@@ -5454,12 +7578,245 @@ var SQLitePersistence = class {
 
 // src/index.ts
 init_Scheduler();
+
+// src/workers/WorkerPool.ts
+var WorkerPool = class {
+  workers = [];
+  config;
+  queue = [];
+  healthCheckTimer = null;
+  stats = {
+    completed: 0,
+    failed: 0
+  };
+  /**
+   * Creates a WorkerPool instance.
+   *
+   * @param config - Configuration options for the pool.
+   */
+  constructor(config = {}) {
+    this.config = {
+      poolSize: config.poolSize ?? 4,
+      minWorkers: config.minWorkers ?? 0,
+      healthCheckInterval: config.healthCheckInterval ?? 3e4,
+      maxExecutionTime: config.maxExecutionTime ?? 3e4,
+      maxMemory: config.maxMemory ?? 0,
+      isolateContexts: config.isolateContexts ?? false,
+      idleTimeout: config.idleTimeout ?? 6e4
+    };
+    this.warmUp();
+    this.startHealthCheck();
+  }
+  /**
+   * Pre-warms the pool by creating the minimum number of workers.
+   */
+  warmUp() {
+    const targetCount = Math.min(this.config.minWorkers, this.config.poolSize);
+    for (let i = 0; i < targetCount; i++) {
+      this.createWorker();
+    }
+  }
+  /**
+   * Creates a new SandboxedWorker and adds it to the pool.
+   *
+   * @returns The newly created worker.
+   */
+  createWorker() {
+    const worker = new SandboxedWorker({
+      maxExecutionTime: this.config.maxExecutionTime,
+      maxMemory: this.config.maxMemory,
+      isolateContexts: this.config.isolateContexts,
+      idleTimeout: this.config.idleTimeout
+    });
+    this.workers.push(worker);
+    return worker;
+  }
+  /**
+   * 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`.
+   */
+  getAvailableWorker() {
+    const readyWorker = this.workers.find((w) => w.isReady());
+    if (readyWorker) {
+      return readyWorker;
+    }
+    if (this.workers.length < this.config.poolSize) {
+      return this.createWorker();
+    }
+    return null;
+  }
+  /**
+   * 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.
+   */
+  async execute(job) {
+    const worker = this.getAvailableWorker();
+    if (worker) {
+      try {
+        await worker.execute(job);
+        this.stats.completed++;
+      } catch (error) {
+        this.stats.failed++;
+        throw error;
+      } finally {
+        this.processQueue();
+      }
+    } else {
+      return new Promise((resolve2, reject) => {
+        this.queue.push({ job, resolve: resolve2, reject });
+      });
+    }
+  }
+  /**
+   * Processes the next job in the queue if a worker is available.
+   */
+  processQueue() {
+    if (this.queue.length === 0) {
+      return;
+    }
+    const worker = this.getAvailableWorker();
+    if (!worker) {
+      return;
+    }
+    const item = this.queue.shift();
+    if (!item) {
+      return;
+    }
+    worker.execute(item.job).then(() => {
+      this.stats.completed++;
+      item.resolve();
+    }).catch((error) => {
+      this.stats.failed++;
+      item.reject(error);
+    }).finally(() => {
+      this.processQueue();
+    });
+  }
+  /**
+   * Starts the periodic health check.
+   */
+  startHealthCheck() {
+    if (this.healthCheckTimer) {
+      return;
+    }
+    this.healthCheckTimer = setInterval(() => {
+      this.performHealthCheck();
+    }, this.config.healthCheckInterval);
+  }
+  /**
+   * Performs a health check on the pool.
+   *
+   * Removes terminated workers and ensures `minWorkers` are available.
+   */
+  performHealthCheck() {
+    this.workers = this.workers.filter((worker) => {
+      if (worker.getState() === "terminated") {
+        worker.terminate().catch(console.error);
+        return false;
+      }
+      return true;
+    });
+    const activeWorkers = this.workers.length;
+    if (activeWorkers < this.config.minWorkers) {
+      const needed = this.config.minWorkers - activeWorkers;
+      for (let i = 0; i < needed; i++) {
+        this.createWorker();
+      }
+    }
+  }
+  /**
+   * Gets the current statistics of the worker pool.
+   *
+   * @returns Snapshot of pool statistics.
+   */
+  getStats() {
+    let ready = 0;
+    let busy = 0;
+    let terminated = 0;
+    for (const worker of this.workers) {
+      const state = worker.getState();
+      if (state === "ready") {
+        ready++;
+      } else if (state === "busy") {
+        busy++;
+      } else if (state === "terminated") {
+        terminated++;
+      }
+    }
+    return {
+      total: this.workers.length,
+      ready,
+      busy,
+      terminated,
+      pending: this.queue.length,
+      completed: this.stats.completed,
+      failed: this.stats.failed
+    };
+  }
+  /**
+   * Shuts down the worker pool.
+   *
+   * Terminates all workers and rejects any pending jobs.
+   */
+  async shutdown() {
+    if (this.healthCheckTimer) {
+      clearInterval(this.healthCheckTimer);
+      this.healthCheckTimer = null;
+    }
+    for (const item of this.queue) {
+      item.reject(new Error("Worker pool is shutting down"));
+    }
+    this.queue = [];
+    await Promise.all(this.workers.map((worker) => worker.terminate().catch(console.error)));
+    this.workers = [];
+  }
+  /**
+   * 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.
+   */
+  async waitForCompletion(timeout = 0) {
+    const startTime = Date.now();
+    return new Promise((resolve2, reject) => {
+      const checkCompletion = () => {
+        const stats = this.getStats();
+        const isComplete = stats.busy === 0 && stats.pending === 0;
+        if (isComplete) {
+          resolve2();
+          return;
+        }
+        if (timeout > 0 && Date.now() - startTime > timeout) {
+          reject(new Error("Wait for completion timeout"));
+          return;
+        }
+        setTimeout(checkCompletion, 100);
+      };
+      checkCompletion();
+    });
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BatchConsumer,
   BufferedPersistence,
+  BullMQDriver,
   ClassNameSerializer,
   Consumer,
   DatabaseDriver,
+  DistributedLock,
+  GrpcDriver,
   Job,
   JsonSerializer,
   KafkaDriver,
@@ -5471,6 +7828,10 @@ init_Scheduler();
   RedisDriver,
   SQLitePersistence,
   SQSDriver,
+  SandboxedWorker,
   Scheduler,
-  Worker
+  StreamEventBackend,
+  SystemEventJob,
+  Worker,
+  WorkerPool
 });