@boringnode/queue 0.0.1-alpha.2 → 0.0.1-alpha.4

package/build/index.js

@@ -1,14 +1,237 @@
+import {
+  parse
+} from "./chunk-5PDDRF5O.js";
+import {
+  Locator,
+  QueueManager,
+  debug_default
+} from "./chunk-CD45GT6E.js";
+import {
+  DEFAULT_ERROR_RETRY_DELAY,
+  DEFAULT_IDLE_DELAY,
+  DEFAULT_PRIORITY,
+  DEFAULT_STALLED_INTERVAL,
+  DEFAULT_STALLED_THRESHOLD,
+  E_INVALID_BASE_DELAY,
+  E_INVALID_MAX_DELAY,
+  E_INVALID_MULTIPLIER,
+  E_JOB_MAX_ATTEMPTS_REACHED,
+  E_JOB_TIMEOUT,
+  exceptions_exports
+} from "./chunk-HMGNQSSG.js";
+
+// src/job_dispatcher.ts
+import { randomUUID } from "crypto";
+var JobDispatcher = class {
+  #name;
+  #payload;
+  #queue = "default";
+  #adapter;
+  #delay;
+  #priority;
+  /**
+   * Create a new job dispatcher.
+   *
+   * @param name - The job class name (used to locate the class at runtime)
+   * @param payload - The data to pass to the job
+   */
+  constructor(name, payload) {
+    this.#name = name;
+    this.#payload = payload;
+  }
+  /**
+   * Set the target queue for this job.
+   *
+   * @param queue - Queue name (default: 'default')
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * await SendEmailJob.dispatch(payload).toQueue('emails')
+   * ```
+   */
+  toQueue(queue) {
+    this.#queue = queue;
+    return this;
+  }
+  /**
+   * Delay the job execution.
+   *
+   * The job will be stored in a delayed state and moved to pending
+   * after the delay expires.
+   *
+   * @param delay - Delay as milliseconds or duration string ('5s', '1h', '7d')
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * // Send reminder in 24 hours
+   * await ReminderJob.dispatch(payload).in('24h')
+   *
+   * // Process in 5 minutes
+   * await CleanupJob.dispatch(payload).in('5m')
+   * ```
+   */
+  in(delay) {
+    this.#delay = delay;
+    return this;
+  }
+  /**
+   * Set the job priority.
+   *
+   * Lower numbers = higher priority. Jobs with lower priority values
+   * are processed before jobs with higher values.
+   *
+   * @param priority - Priority level (1-10, default: 5)
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * // High priority job
+   * await UrgentJob.dispatch(payload).priority(1)
+   *
+   * // Low priority job
+   * await BackgroundJob.dispatch(payload).priority(10)
+   * ```
+   */
+  priority(priority) {
+    this.#priority = priority;
+    return this;
+  }
+  /**
+   * Use a specific adapter for this job.
+   *
+   * @param adapter - Adapter name or factory function
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * // Use named adapter
+   * await Job.dispatch(payload).with('redis')
+   *
+   * // Use custom adapter instance
+   * await Job.dispatch(payload).with(() => new CustomAdapter())
+   * ```
+   */
+  with(adapter) {
+    this.#adapter = adapter;
+    return this;
+  }
+  /**
+   * Dispatch the job to the queue.
+   *
+   * @returns The unique job ID
+   *
+   * @example
+   * ```typescript
+   * const jobId = await SendEmailJob.dispatch(payload).run()
+   * console.log(`Dispatched job: ${jobId}`)
+   * ```
+   */
+  async run() {
+    const id = randomUUID();
+    debug_default("dispatching job %s with id %s using payload %s", this.#name, id, this.#payload);
+    const adapter = this.#getAdapterInstance();
+    const payload = {
+      id,
+      name: this.#name,
+      payload: this.#payload,
+      attempts: 0,
+      priority: this.#priority
+    };
+    if (this.#delay) {
+      const parsedDelay = parse(this.#delay);
+      await adapter.pushLaterOn(this.#queue, payload, parsedDelay);
+    } else {
+      await adapter.pushOn(this.#queue, payload);
+    }
+    return id;
+  }
+  /**
+   * Thenable implementation for auto-dispatch when awaited.
+   *
+   * Allows `await Job.dispatch(payload)` without explicit `.run()`.
+   *
+   * @param onFulfilled - Success callback
+   * @param onRejected - Error callback
+   * @returns Promise resolving to the job ID
+   */
+  then(onFulfilled, onRejected) {
+    return this.run().then(onFulfilled, onRejected);
+  }
+  #getAdapterInstance() {
+    if (!this.#adapter) {
+      return QueueManager.use();
+    }
+    if (typeof this.#adapter === "string") {
+      return QueueManager.use(this.#adapter);
+    }
+    return this.#adapter();
+  }
+};
+
 // src/job.ts
-import { JobDispatcher } from "#src/job_dispatcher";
 var Job = class {
   #payload;
+  #context;
+  /** Static options for this job class (queue, retries, timeout, etc.) */
   static options = {};
+  /** The payload data passed to this job instance */
   get payload() {
     return this.#payload;
   }
-  constructor(payload) {
+  /**
+   * Context information for the current job execution.
+   *
+   * Provides metadata such as job ID, current attempt number,
+   * queue name, priority, and timing information.
+   *
+   * @example
+   * ```typescript
+   * async execute() {
+   *   if (this.context.attempt > 1) {
+   *     console.log(`Retry attempt ${this.context.attempt}`)
+   *   }
+   *   console.log(`Processing job ${this.context.jobId} on queue ${this.context.queue}`)
+   * }
+   * ```
+   */
+  get context() {
+    return this.#context;
+  }
+  /**
+   * Create a new job instance.
+   *
+   * @param payload - The data to be processed by this job
+   * @param context - The job execution context (provided by the worker)
+   */
+  constructor(payload, context) {
     this.#payload = payload;
+    this.#context = Object.freeze(context);
   }
+  /**
+   * Dispatch this job to the queue.
+   *
+   * Returns a JobDispatcher for fluent configuration before dispatching.
+   * The job is not actually dispatched until `.run()` is called or the
+   * dispatcher is awaited.
+   *
+   * @param payload - The data to pass to the job
+   * @returns A JobDispatcher for fluent configuration
+   *
+   * @example
+   * ```typescript
+   * // Simple dispatch
+   * await SendEmailJob.dispatch({ to: 'user@example.com', subject: 'Hello' })
+   *
+   * // With options
+   * await SendEmailJob.dispatch({ to: 'user@example.com' })
+   *   .toQueue('high-priority')
+   *   .priority(1)
+   *   .in('5m')
+   *   .run()
+   * ```
+   */
   static dispatch(payload) {
     const dispatcher = new JobDispatcher(
       this.jobName,
@@ -28,50 +251,164 @@ var Job = class {
 };
 
 // src/worker.ts
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 import { setTimeout } from "timers/promises";
-import debug from "#src/debug";
-import { parse } from "#src/utils";
-import * as errors from "#src/exceptions";
-import { QueueManager } from "#src/queue_manager";
-import { JobPool } from "#src/job_pool";
-import { Locator } from "#src/locator";
+
+// src/job_pool.ts
+var JobPool = class {
+  #activeJobs = /* @__PURE__ */ new Map();
+  /** Number of currently running jobs */
+  get size() {
+    return this.#activeJobs.size;
+  }
+  /**
+   * Check if the pool has no running jobs.
+   *
+   * @returns True if no jobs are running
+   */
+  isEmpty() {
+    return this.#activeJobs.size === 0;
+  }
+  /**
+   * Check if the pool can accept more jobs.
+   *
+   * @param concurrency - Maximum number of concurrent jobs
+   * @returns True if there's room for more jobs
+   */
+  hasCapacity(concurrency) {
+    return this.#activeJobs.size < concurrency;
+  }
+  /**
+   * Add a job to the pool.
+   *
+   * @param job - The acquired job data
+   * @param queue - The queue the job came from
+   * @param promise - Promise that resolves when the job completes
+   */
+  add(job, queue, promise) {
+    this.#activeJobs.set(job.id, { promise, job, queue });
+  }
+  /**
+   * Wait for the next job to complete and return it.
+   *
+   * Uses `Promise.race()` internally, so the fastest job wins.
+   * The completed job is removed from the pool.
+   *
+   * @returns The first job to complete (success or failure)
+   */
+  async waitForNextCompletion() {
+    const completedJobId = await Promise.race(
+      [...this.#activeJobs.entries()].map(async ([id, { promise }]) => {
+        try {
+          await promise;
+        } catch {
+        }
+        return id;
+      })
+    );
+    const completed = this.#activeJobs.get(completedJobId);
+    this.#activeJobs.delete(completedJobId);
+    return completed;
+  }
+  /**
+   * Wait for all running jobs to complete.
+   *
+   * Used during graceful shutdown to ensure no jobs are abandoned.
+   * Clears the pool after all jobs finish.
+   */
+  async drain() {
+    const promises = [...this.#activeJobs.values()].map(async ({ promise }) => {
+      try {
+        await promise;
+      } catch {
+      }
+    });
+    await Promise.all(promises);
+    this.#activeJobs.clear();
+  }
+};
+
+// src/worker.ts
 var Worker = class {
   #id;
   #config;
+  #idleDelay;
+  #stalledInterval;
+  #stalledThreshold;
+  #maxStalledCount;
+  #concurrency;
+  #gracefulShutdown;
+  #onShutdownSignal;
   #adapter;
   #running = false;
   #initialized = false;
   #generator;
   #pool;
+  #lastStalledCheck = 0;
+  #shutdownHandler;
+  /** Unique identifier for this worker instance */
   get id() {
     return this.#id;
   }
+  /**
+   * Create a new worker instance.
+   *
+   * @param config - Queue configuration including adapter and worker settings
+   */
   constructor(config) {
     this.#config = config;
-    this.#id = randomUUID();
-    debug("created worker with id %s and config %O", this.#id, config);
+    this.#id = randomUUID2();
+    this.#idleDelay = parse(config.worker?.idleDelay ?? DEFAULT_IDLE_DELAY);
+    this.#stalledInterval = parse(config.worker?.stalledInterval ?? DEFAULT_STALLED_INTERVAL);
+    this.#stalledThreshold = parse(config.worker?.stalledThreshold ?? DEFAULT_STALLED_THRESHOLD);
+    this.#maxStalledCount = config.worker?.maxStalledCount ?? 1;
+    this.#concurrency = config.worker?.concurrency ?? 1;
+    this.#gracefulShutdown = config.worker?.gracefulShutdown ?? true;
+    this.#onShutdownSignal = config.worker?.onShutdownSignal;
+    debug_default("created worker with id %s and config %O", this.#id, config);
   }
+  /**
+   * Initialize the worker (called automatically by `start()`).
+   *
+   * Sets up the QueueManager and adapter connection.
+   */
   async init() {
     if (this.#initialized) {
       return;
     }
-    debug("initializing worker %s", this.#id);
+    debug_default("initializing worker %s", this.#id);
     await QueueManager.init(this.#config);
     this.#adapter = QueueManager.use();
     this.#adapter.setWorkerId(this.#id);
     this.#initialized = true;
-    debug("worker %s initialized", this.#id);
+    debug_default("worker %s initialized", this.#id);
   }
+  /**
+   * Start processing jobs from the specified queues.
+   *
+   * This method blocks until the worker is stopped (via `stop()` or signal).
+   * Jobs are processed concurrently up to the configured concurrency limit.
+   *
+   * @param queues - Queue names to process (default: ['default'])
+   *
+   * @example
+   * ```typescript
+   * // Process single queue
+   * await worker.start()
+   *
+   * // Process multiple queues (priority order)
+   * await worker.start(['high-priority', 'default', 'low-priority'])
+   * ```
+   */
   async start(queues = ["default"]) {
     await this.init();
     if (this.#running) {
-      debug("worker %s is already running", this.#id);
+      debug_default("worker %s is already running", this.#id);
       return;
     }
     this.#running = true;
-    debug("starting worker %s on queues: %O", this.#id, queues);
-    await this.#setupGracefulShutdown();
+    debug_default("starting worker %s on queues: %O", this.#id, queues);
+    this.#setupGracefulShutdown();
     for await (const cycle of this.process(queues)) {
       if (["started", "completed"].includes(cycle.type)) {
         continue;
@@ -79,25 +416,53 @@ var Worker = class {
       if (["idle", "error"].includes(cycle.type)) {
         const delay = parse(cycle.suggestedDelay);
         if (cycle.type === "error") {
-          debug("worker %s encountered an error: %O", this.#id, cycle.error);
+          debug_default("worker %s encountered an error: %O", this.#id, cycle.error);
         } else {
-          debug("worker %s is idle, waiting for %dms", this.#id, delay);
+          debug_default("worker %s is idle, waiting for %dms", this.#id, delay);
         }
         await setTimeout(delay);
       }
     }
   }
+  /**
+   * Stop the worker gracefully.
+   *
+   * Waits for all running jobs to complete before shutting down.
+   * Called automatically on SIGINT/SIGTERM if gracefulShutdown is enabled.
+   */
   async stop() {
-    debug("stopping worker %s", this.#id);
+    debug_default("stopping worker %s", this.#id);
     this.#running = false;
     if (this.#pool) {
-      debug("worker %s: waiting for %d running jobs to complete", this.#id, this.#pool.size);
+      debug_default("worker %s: waiting for %d running jobs to complete", this.#id, this.#pool.size);
       await this.#pool.drain();
     }
     if (this.#adapter) {
       await this.#adapter.destroy();
     }
+    this.#removeShutdownHandlers();
   }
+  /**
+   * Process a single cycle and return the result.
+   *
+   * Useful for testing or when you need fine-grained control.
+   * Each cycle may start new jobs, complete a job, or return idle.
+   *
+   * @param queues - Queue names to process
+   * @returns The cycle result, or null if the worker was stopped
+   *
+   * @example
+   * ```typescript
+   * const worker = new Worker(config)
+   *
+   * // Process cycles manually
+   * let cycle = await worker.processCycle(['default'])
+   * while (cycle) {
+   *   console.log('Cycle:', cycle.type)
+   *   cycle = await worker.processCycle(['default'])
+   * }
+   * ```
+   */
   async processCycle(queues) {
     await this.init();
     this.#running = true;
@@ -111,26 +476,58 @@ var Worker = class {
     }
     return result.value;
   }
+  /**
+   * Generator that yields worker cycle events.
+   *
+   * Low-level API for processing jobs. Yields events for:
+   * - `started`: A new job began execution
+   * - `completed`: A job finished (success or failure)
+   * - `idle`: No jobs available, suggest waiting
+   * - `error`: An error occurred during processing
+   *
+   * @param queues - Queue names to process
+   * @yields WorkerCycle events
+   *
+   * @example
+   * ```typescript
+   * for await (const cycle of worker.process(['default'])) {
+   *   switch (cycle.type) {
+   *     case 'started':
+   *       console.log(`Started job ${cycle.job.id}`)
+   *       break
+   *     case 'completed':
+   *       console.log(`Completed job ${cycle.job.id}`)
+   *       break
+   *     case 'idle':
+   *       await sleep(cycle.suggestedDelay)
+   *       break
+   *   }
+   * }
+   * ```
+   */
   async *process(queues) {
-    const pollingInterval = parse(this.#config.worker?.pollingInterval || "2s");
     this.#pool = new JobPool();
     while (this.#running) {
       try {
+        await this.#checkStalledJobs(queues);
         yield* this.#fillPool(queues);
         if (this.#pool.isEmpty()) {
-          yield { type: "idle", suggestedDelay: pollingInterval };
+          yield { type: "idle", suggestedDelay: this.#idleDelay };
           continue;
         }
         const completed = await this.#pool.waitForNextCompletion();
         yield { type: "completed", queue: completed.queue, job: completed.job };
       } catch (error) {
-        yield { type: "error", error, suggestedDelay: parse("5s") };
+        yield {
+          type: "error",
+          error,
+          suggestedDelay: parse(DEFAULT_ERROR_RETRY_DELAY)
+        };
       }
     }
   }
   async *#fillPool(queues) {
-    const concurrency = this.#config.worker?.concurrency || 1;
-    const slotsAvailable = concurrency - this.#pool.size;
+    const slotsAvailable = this.#concurrency - this.#pool.size;
     if (slotsAvailable <= 0) return;
     const popPromises = Array.from({ length: slotsAvailable }, () => this.#acquireNextJob(queues));
     const results = await Promise.all(popPromises);
@@ -144,44 +541,44 @@ var Worker = class {
   }
   async #execute(job, queue) {
     const startTime = performance.now();
-    debug("worker %s: executing job %s (%s)", this.#id, job.id, job.name);
+    debug_default("worker %s: executing job %s (%s)", this.#id, job.id, job.name);
     const { instance, options, timeout } = await this.#initJob(job, queue);
     try {
       await this.#executeWithTimeout(instance, timeout);
       await this.#adapter.completeJob(job.id, queue);
       const duration = (performance.now() - startTime).toFixed(2);
-      debug("worker %s: successfully executed job %s in %dms", this.#id, job.id, duration);
+      debug_default("worker %s: successfully executed job %s in %dms", this.#id, job.id, duration);
     } catch (e) {
-      const isTimeout = e instanceof errors.E_JOB_TIMEOUT;
+      const isTimeout = e instanceof E_JOB_TIMEOUT;
       if (isTimeout && options.failOnTimeout) {
-        debug("worker %s: job %s timed out and failOnTimeout is set", this.#id, job.id);
+        debug_default("worker %s: job %s timed out and failOnTimeout is set", this.#id, job.id);
         await this.#adapter.failJob(job.id, queue, e);
         await instance.failed?.(e);
         return;
       }
       const mergedConfig = QueueManager.getMergedRetryConfig(queue, options.retry);
       if (typeof mergedConfig.maxRetries === "undefined" || mergedConfig.maxRetries <= 0) {
-        debug("worker %s: job %s has no retries configured, marking as failed", this.#id, job.id);
+        debug_default("worker %s: job %s has no retries configured, marking as failed", this.#id, job.id);
         await this.#adapter.failJob(job.id, queue, e);
         await instance.failed?.(e);
         return;
       }
       if (job.attempts >= mergedConfig.maxRetries) {
-        debug(
+        debug_default(
           "worker %s: job %s has exceeded max retries (%d), marking as failed",
           this.#id,
           job.id,
           mergedConfig.maxRetries
         );
         await this.#adapter.failJob(job.id, queue, e);
-        const exception = new errors.E_JOB_MAX_ATTEMPTS_REACHED([job.name]);
+        const exception = new E_JOB_MAX_ATTEMPTS_REACHED([job.name]);
         await instance.failed?.(exception);
         return;
       }
       if (mergedConfig.backoff) {
         const strategy = mergedConfig.backoff();
         const nextRetryAt = strategy.getNextRetryAt(job.attempts + 1);
-        debug("worker %s: job %s will retry at %s", this.#id, job.id, nextRetryAt.toISOString());
+        debug_default("worker %s: job %s will retry at %s", this.#id, job.id, nextRetryAt.toISOString());
         await this.#adapter.retryJob(job.id, queue, nextRetryAt);
         return;
       }
@@ -191,12 +588,22 @@ var Worker = class {
   async #initJob(job, queue) {
     try {
       const JobClass = Locator.getOrThrow(job.name);
-      const instance = new JobClass(job.payload);
+      const context = Object.freeze({
+        jobId: job.id,
+        name: job.name,
+        attempt: job.attempts + 1,
+        queue,
+        priority: job.priority ?? DEFAULT_PRIORITY,
+        acquiredAt: new Date(job.acquiredAt),
+        stalledCount: job.stalledCount ?? 0
+      });
+      const jobFactory = QueueManager.getJobFactory();
+      const instance = jobFactory ? await jobFactory(JobClass, job.payload, context) : new JobClass(job.payload, context);
       const options = JobClass.options || {};
       const timeout = this.#getJobTimeout(options);
       return { instance, options, timeout };
     } catch (error) {
-      debug("worker %s: failed to initialize job %s (%s)", this.#id, job.id, job.name);
+      debug_default("worker %s: failed to initialize job %s (%s)", this.#id, job.id, job.name);
       await this.#adapter.failJob(job.id, queue, error);
       throw error;
     }
@@ -217,7 +624,7 @@ var Worker = class {
     const signal = AbortSignal.timeout(timeout);
     const abortPromise = new Promise((_, reject) => {
       signal.addEventListener("abort", () => {
-        reject(new errors.E_JOB_TIMEOUT([instance.constructor.name, timeout]));
+        reject(new E_JOB_TIMEOUT([instance.constructor.name, timeout]));
       });
     });
     await Promise.race([instance.execute(signal), abortPromise]);
@@ -228,126 +635,89 @@ var Worker = class {
       if (!job) {
         continue;
       }
-      debug("worker %s: acquired job %s", this.#id, job.id);
+      debug_default("worker %s: acquired job %s", this.#id, job.id);
       return { job, queue };
     }
     return null;
   }
-  async #setupGracefulShutdown() {
-    const shutdown = async () => {
-      debug("received shutdown signal, stopping worker...");
-      await this.stop();
-      process.exit(0);
-    };
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
-  }
-};
-
-// src/queue_manager.ts
-import * as errors2 from "#src/exceptions";
-import debug2 from "#src/debug";
-import { Locator as Locator2 } from "#src/locator";
-var QueueManagerSingleton = class {
-  #defaultAdapter;
-  #adapters = {};
-  #adapterInstances = /* @__PURE__ */ new Map();
-  #globalRetryConfig;
-  #queueConfigs = /* @__PURE__ */ new Map();
-  async init(config) {
-    debug2("initializing queue manager with config: %O", config);
-    this.#validateConfig(config);
-    this.#adapterInstances.clear();
-    this.#defaultAdapter = config.default;
-    this.#adapters = config.adapters;
-    this.#globalRetryConfig = config.retry;
-    if (config.queues) {
-      for (const [queue, queueConfig] of Object.entries(config.queues)) {
-        this.#queueConfigs.set(queue, queueConfig);
-      }
-    }
-    await Locator2.registerFromGlob(config.locations);
-    return this;
-  }
-  use(adapter) {
-    if (!adapter) {
-      adapter = this.#defaultAdapter;
-    }
-    const cached = this.#adapterInstances.get(adapter);
-    if (cached) {
-      return cached;
-    }
-    const adapterFactory = this.#adapters[adapter];
-    if (!adapterFactory) {
-      throw new errors2.E_CONFIGURATION_ERROR([`Adapter "${adapter}" is not registered`]);
+  async #checkStalledJobs(queues) {
+    const now = Date.now();
+    if (now - this.#lastStalledCheck < this.#stalledInterval) {
+      return;
     }
-    debug2('using adapter "%s"', adapter);
-    try {
-      const instance = adapterFactory();
-      this.#adapterInstances.set(adapter, instance);
-      return instance;
-    } catch (error) {
-      throw new Error();
+    this.#lastStalledCheck = now;
+    for (const queue of queues) {
+      const recovered = await this.#adapter.recoverStalledJobs(
+        queue,
+        this.#stalledThreshold,
+        this.#maxStalledCount
+      );
+      if (recovered > 0) {
+        debug_default("worker %s: recovered %d stalled jobs from queue %s", this.#id, recovered, queue);
+      }
     }
   }
-  /**
-   * Priority: job > queue > global
-   */
-  getMergedRetryConfig(queue, jobRetryConfig) {
-    const queueConfig = this.#queueConfigs.get(queue);
-    const queueRetryConfig = queueConfig?.retry || {};
-    let maxRetries = jobRetryConfig?.maxRetries || queueRetryConfig.maxRetries || this.#globalRetryConfig?.maxRetries || 0;
-    let backoff = jobRetryConfig?.backoff || queueRetryConfig.backoff || this.#globalRetryConfig?.backoff;
-    return { maxRetries, backoff };
-  }
-  #validateConfig(config) {
-    if (!config.adapters || Object.keys(config.adapters).length === 0) {
-      throw new errors2.E_CONFIGURATION_ERROR(["At least one adapter must be configured"]);
-    }
-    if (!config.default) {
-      throw new errors2.E_CONFIGURATION_ERROR(["Default adapter must be specified"]);
-    }
-    if (!config.locations || config.locations.length === 0) {
-      throw new errors2.E_CONFIGURATION_ERROR(["Job locations must be specified"]);
-    }
-    if (!config.adapters[config.default]) {
-      throw new errors2.E_CONFIGURATION_ERROR([
-        `Default adapter "${config.default}" not found in adapters configuration`
-      ]);
+  #setupGracefulShutdown() {
+    if (!this.#gracefulShutdown) {
+      return;
     }
-    for (const [name, factory] of Object.entries(config.adapters)) {
-      if (typeof factory !== "function") {
-        throw new errors2.E_CONFIGURATION_ERROR([`Adapter "${name}" must be a factory function`]);
+    this.#shutdownHandler = async () => {
+      debug_default("received shutdown signal, stopping worker...");
+      if (this.#onShutdownSignal) {
+        await this.#onShutdownSignal();
       }
-    }
+      await this.stop();
+    };
+    process.on("SIGINT", this.#shutdownHandler);
+    process.on("SIGTERM", this.#shutdownHandler);
   }
-  async destroy() {
-    for (const [name, adapter] of this.#adapterInstances) {
-      debug2('destroying adapter "%s"', name);
-      await adapter.destroy();
+  #removeShutdownHandlers() {
+    if (this.#shutdownHandler) {
+      process.off("SIGINT", this.#shutdownHandler);
+      process.off("SIGTERM", this.#shutdownHandler);
+      this.#shutdownHandler = void 0;
     }
-    this.#adapterInstances.clear();
   }
 };
-var QueueManager2 = new QueueManagerSingleton();
 
 // src/strategies/backoff_strategy.ts
-import * as errors3 from "#src/exceptions";
-import { parse as parse2 } from "#src/utils";
 import { RuntimeException } from "@poppinss/utils";
 import { assertUnreachable } from "@poppinss/utils/assert";
 var BackoffStrategy = class {
   #config;
+  /**
+   * Create a new backoff strategy.
+   *
+   * @param config - Backoff configuration
+   * @throws {E_INVALID_BASE_DELAY} If baseDelay is not positive
+   * @throws {E_INVALID_MAX_DELAY} If maxDelay is invalid
+   * @throws {E_INVALID_MULTIPLIER} If multiplier is invalid
+   */
   constructor(config) {
     this.#config = config;
     this.#validateConfig();
   }
+  /**
+   * Calculate the delay for a given attempt number.
+   *
+   * @param attempt - The attempt number (1-based)
+   * @returns Delay in milliseconds
+   * @throws {RuntimeException} If attempt is less than 1
+   *
+   * @example
+   * ```typescript
+   * // Exponential: 1s, 2s, 4s, 8s, 16s, ...
+   * strategy.calculateDelay(1) // 1000
+   * strategy.calculateDelay(2) // 2000
+   * strategy.calculateDelay(3) // 4000
+   * ```
+   */
   calculateDelay(attempt) {
     if (attempt < 1) {
       throw new RuntimeException("Attempt number must be >= 1");
     }
-    const baseDelayMs = parse2(this.#config.baseDelay);
-    const maxDelayMs = this.#config.maxDelay ? parse2(this.#config.maxDelay) : Infinity;
+    const baseDelayMs = parse(this.#config.baseDelay);
+    const maxDelayMs = this.#config.maxDelay ? parse(this.#config.maxDelay) : Infinity;
     const multiplier = this.#config.multiplier ?? 2;
     let delay;
     switch (this.#config.strategy) {
@@ -369,39 +739,56 @@ var BackoffStrategy = class {
     }
     return Math.floor(delay);
   }
+  /**
+   * Get the Date when the next retry should occur.
+   *
+   * @param attempt - The attempt number (1-based)
+   * @returns Date for the next retry
+   *
+   * @example
+   * ```typescript
+   * const nextRetry = strategy.getNextRetryAt(3)
+   * console.log(`Retry at: ${nextRetry.toISOString()}`)
+   * ```
+   */
   getNextRetryAt(attempt) {
     const delay = this.calculateDelay(attempt);
     return new Date(Date.now() + delay);
   }
+  /**
+   * Get a frozen copy of the configuration.
+   *
+   * @returns Readonly configuration object
+   */
   getConfig() {
     return Object.freeze({ ...this.#config });
   }
   #validateConfig() {
-    const baseDelayMs = parse2(this.#config.baseDelay);
+    const baseDelayMs = parse(this.#config.baseDelay);
     if (baseDelayMs <= 0) {
-      throw new errors3.E_INVALID_BASE_DELAY([
+      throw new E_INVALID_BASE_DELAY([
         "Base delay must be a positive integer greater than zero"
       ]);
     }
     if (this.#config.maxDelay) {
-      const maxDelayMs = parse2(this.#config.maxDelay);
+      const maxDelayMs = parse(this.#config.maxDelay);
       if (maxDelayMs <= 0) {
-        throw new errors3.E_INVALID_MAX_DELAY([
+        throw new E_INVALID_MAX_DELAY([
           "Max delay must be a positive integer greater than zero"
         ]);
       }
       if (maxDelayMs <= baseDelayMs) {
-        throw new errors3.E_INVALID_MAX_DELAY(["Max delay should be greater than base delay"]);
+        throw new E_INVALID_MAX_DELAY(["Max delay should be greater than base delay"]);
       }
     }
     if (this.#config.multiplier !== void 0) {
       if (this.#config.multiplier <= 0) {
-        throw new errors3.E_INVALID_MULTIPLIER([
+        throw new E_INVALID_MULTIPLIER([
           "Multiplier must be a positive number greater than zero"
         ]);
       }
       if (this.#config.strategy === "exponential" && this.#config.multiplier < 1) {
-        throw new errors3.E_INVALID_MULTIPLIER(["Exponential strategy multiplier should be >= 1"]);
+        throw new E_INVALID_MULTIPLIER(["Exponential strategy multiplier should be >= 1"]);
       }
     }
   }
@@ -440,9 +827,11 @@ function customBackoff(config) {
 }
 export {
   Job,
-  QueueManager2 as QueueManager,
+  Locator,
+  QueueManager,
   Worker,
   customBackoff,
+  exceptions_exports as errors,
   exponentialBackoff,
   fixedBackoff,
   linearBackoff