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

package/build/index.js

@@ -1,116 +1,27 @@
 import {
-  E_CONFIGURATION_ERROR,
+  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_DURATION_EXPRESSION,
   E_INVALID_MAX_DELAY,
   E_INVALID_MULTIPLIER,
   E_JOB_MAX_ATTEMPTS_REACHED,
   E_JOB_TIMEOUT,
-  Locator,
-  debug_default
-} from "./chunk-Y6KR3UIR.js";
+  exceptions_exports
+} from "./chunk-HMGNQSSG.js";
 
 // src/job_dispatcher.ts
 import { randomUUID } from "crypto";
-
-// src/queue_manager.ts
-var QueueManagerSingleton = class {
-  #defaultAdapter;
-  #adapters = {};
-  #adapterInstances = /* @__PURE__ */ new Map();
-  #globalRetryConfig;
-  #queueConfigs = /* @__PURE__ */ new Map();
-  async init(config) {
-    debug_default("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 Locator.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 E_CONFIGURATION_ERROR([`Adapter "${adapter}" is not registered`]);
-    }
-    debug_default('using adapter "%s"', adapter);
-    try {
-      const instance = adapterFactory();
-      this.#adapterInstances.set(adapter, instance);
-      return instance;
-    } catch (error) {
-      throw new Error();
-    }
-  }
-  /**
-   * 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 E_CONFIGURATION_ERROR(["At least one adapter must be configured"]);
-    }
-    if (!config.default) {
-      throw new E_CONFIGURATION_ERROR(["Default adapter must be specified"]);
-    }
-    if (!config.locations || config.locations.length === 0) {
-      throw new E_CONFIGURATION_ERROR(["Job locations must be specified"]);
-    }
-    if (!config.adapters[config.default]) {
-      throw new E_CONFIGURATION_ERROR([
-        `Default adapter "${config.default}" not found in adapters configuration`
-      ]);
-    }
-    for (const [name, factory] of Object.entries(config.adapters)) {
-      if (typeof factory !== "function") {
-        throw new E_CONFIGURATION_ERROR([`Adapter "${name}" must be a factory function`]);
-      }
-    }
-  }
-  async destroy() {
-    for (const [name, adapter] of this.#adapterInstances) {
-      debug_default('destroying adapter "%s"', name);
-      await adapter.destroy();
-    }
-    this.#adapterInstances.clear();
-  }
-};
-var QueueManager = new QueueManagerSingleton();
-
-// src/utils.ts
-import { parse as parseDuration } from "@lukeed/ms";
-function parse(duration) {
-  if (typeof duration === "number") {
-    return duration;
-  }
-  const milliseconds = parseDuration(duration);
-  if (typeof milliseconds === "undefined") {
-    throw new E_INVALID_DURATION_EXPRESSION([duration]);
-  }
-  return milliseconds;
-}
-
-// src/job_dispatcher.ts
 var JobDispatcher = class {
   #name;
   #payload;
@@ -118,26 +29,105 @@ var JobDispatcher = class {
   #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);
@@ -157,6 +147,15 @@ var JobDispatcher = class {
     }
     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);
   }
@@ -174,13 +173,65 @@ var JobDispatcher = class {
 // src/job.ts
 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,
@@ -206,18 +257,45 @@ import { setTimeout } from "timers/promises";
 // 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 }]) => {
@@ -232,6 +310,12 @@ var JobPool = class {
     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 {
@@ -248,19 +332,46 @@ var JobPool = class {
 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 = 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;
@@ -272,6 +383,23 @@ var Worker = class {
     this.#initialized = true;
     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) {
@@ -280,7 +408,7 @@ var Worker = class {
     }
     this.#running = true;
     debug_default("starting worker %s on queues: %O", this.#id, queues);
-    await this.#setupGracefulShutdown();
+    this.#setupGracefulShutdown();
     for await (const cycle of this.process(queues)) {
       if (["started", "completed"].includes(cycle.type)) {
         continue;
@@ -296,6 +424,12 @@ var Worker = class {
       }
     }
   }
+  /**
+   * 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_default("stopping worker %s", this.#id);
     this.#running = false;
@@ -306,7 +440,29 @@ var Worker = class {
     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;
@@ -320,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);
@@ -400,7 +588,17 @@ 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 };
@@ -442,14 +640,43 @@ var Worker = class {
     }
     return null;
   }
-  async #setupGracefulShutdown() {
-    const shutdown = async () => {
+  async #checkStalledJobs(queues) {
+    const now = Date.now();
+    if (now - this.#lastStalledCheck < this.#stalledInterval) {
+      return;
+    }
+    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);
+      }
+    }
+  }
+  #setupGracefulShutdown() {
+    if (!this.#gracefulShutdown) {
+      return;
+    }
+    this.#shutdownHandler = async () => {
       debug_default("received shutdown signal, stopping worker...");
+      if (this.#onShutdownSignal) {
+        await this.#onShutdownSignal();
+      }
       await this.stop();
-      process.exit(0);
     };
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
+    process.on("SIGINT", this.#shutdownHandler);
+    process.on("SIGTERM", this.#shutdownHandler);
+  }
+  #removeShutdownHandlers() {
+    if (this.#shutdownHandler) {
+      process.off("SIGINT", this.#shutdownHandler);
+      process.off("SIGTERM", this.#shutdownHandler);
+      this.#shutdownHandler = void 0;
+    }
   }
 };
 
@@ -458,10 +685,33 @@ 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");
@@ -489,10 +739,27 @@ 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 });
   }
@@ -560,9 +827,11 @@ function customBackoff(config) {
 }
 export {
   Job,
+  Locator,
   QueueManager,
   Worker,
   customBackoff,
+  exceptions_exports as errors,
   exponentialBackoff,
   fixedBackoff,
   linearBackoff