@boringnode/queue 0.0.1-alpha.3 → 0.1.0

package/build/index.js

@@ -1,116 +1,29 @@
 import {
-  E_CONFIGURATION_ERROR,
+  parse
+} from "./chunk-NPQKBCCY.js";
+import {
+  Locator,
+  QueueManager,
+  debug_default
+} from "./chunk-US7THLSZ.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_CRON_EXPRESSION,
   E_INVALID_MAX_DELAY,
   E_INVALID_MULTIPLIER,
+  E_INVALID_SCHEDULE_CONFIG,
   E_JOB_MAX_ATTEMPTS_REACHED,
   E_JOB_TIMEOUT,
-  Locator,
-  debug_default
-} from "./chunk-Y6KR3UIR.js";
+  exceptions_exports
+} from "./chunk-SMOKFZ46.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 +31,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 A DispatchResult containing the jobId
+   *
+   * @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);
@@ -155,8 +147,19 @@ var JobDispatcher = class {
     } else {
       await adapter.pushOn(this.#queue, payload);
     }
-    return id;
+    return {
+      jobId: 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 DispatchResult
+   */
   then(onFulfilled, onRejected) {
     return this.run().then(onFulfilled, onRejected);
   }
@@ -171,16 +174,221 @@ var JobDispatcher = class {
   }
 };
 
+// src/schedule_builder.ts
+import { CronExpressionParser } from "cron-parser";
+var ScheduleBuilder = class {
+  #jobName;
+  #payload;
+  #id;
+  #cronExpression;
+  #everyMs;
+  #timezone = "UTC";
+  #from;
+  #to;
+  #limit;
+  constructor(jobName, payload) {
+    this.#jobName = jobName;
+    this.#payload = payload;
+  }
+  /**
+   * Set a custom schedule ID.
+   * If not specified, defaults to the job name.
+   * If a schedule with this ID exists, it will be updated (upsert).
+   */
+  id(scheduleId) {
+    this.#id = scheduleId;
+    return this;
+  }
+  /**
+   * Set a cron expression for the schedule.
+   * Mutually exclusive with `every()`.
+   */
+  cron(expression) {
+    this.#cronExpression = expression;
+    return this;
+  }
+  /**
+   * Set a repeating interval for the schedule.
+   * Mutually exclusive with `cron()`.
+   */
+  every(interval) {
+    this.#everyMs = parse(interval);
+    return this;
+  }
+  /**
+   * Set the timezone for cron evaluation.
+   * @default 'UTC'
+   */
+  timezone(tz) {
+    this.#timezone = tz;
+    return this;
+  }
+  /**
+   * Set the start boundary for the schedule.
+   * No jobs will be dispatched before this date.
+   */
+  from(date) {
+    this.#from = date;
+    return this;
+  }
+  /**
+   * Set the end boundary for the schedule.
+   * No jobs will be dispatched after this date.
+   */
+  to(date) {
+    this.#to = date;
+    return this;
+  }
+  /**
+   * Set both start and end boundaries for the schedule.
+   * Shorthand for `.from(start).to(end)`.
+   */
+  between(from, to) {
+    return this.from(from).to(to);
+  }
+  /**
+   * Set the maximum number of runs for this schedule.
+   */
+  limit(maxRuns) {
+    this.#limit = maxRuns;
+    return this;
+  }
+  /**
+   * Create the schedule and return the schedule ID.
+   */
+  async run() {
+    if (!this.#cronExpression && !this.#everyMs) {
+      throw new E_INVALID_SCHEDULE_CONFIG([
+        "Schedule must have either a cron expression or an interval"
+      ]);
+    }
+    if (this.#cronExpression && this.#everyMs) {
+      throw new E_INVALID_SCHEDULE_CONFIG([
+        "Schedule cannot have both a cron expression and an interval"
+      ]);
+    }
+    if (this.#cronExpression) {
+      try {
+        CronExpressionParser.parse(this.#cronExpression, { tz: this.#timezone });
+      } catch (error) {
+        throw new E_INVALID_CRON_EXPRESSION([this.#cronExpression, error.message]);
+      }
+    }
+    const config = {
+      id: this.#id ?? this.#jobName,
+      jobName: this.#jobName,
+      payload: this.#payload,
+      cronExpression: this.#cronExpression,
+      everyMs: this.#everyMs,
+      timezone: this.#timezone,
+      from: this.#from,
+      to: this.#to,
+      limit: this.#limit
+    };
+    const adapter = QueueManager.use();
+    const scheduleId = await adapter.createSchedule(config);
+    const nextRunAt = this.#calculateNextRunAt();
+    await adapter.updateSchedule(scheduleId, { nextRunAt });
+    return { scheduleId };
+  }
+  /**
+   * Calculate the next run time based on cron or interval.
+   */
+  #calculateNextRunAt() {
+    const now = /* @__PURE__ */ new Date();
+    let nextRun;
+    if (this.#cronExpression) {
+      const cron = CronExpressionParser.parse(this.#cronExpression, {
+        currentDate: now,
+        tz: this.#timezone
+      });
+      nextRun = cron.next().toDate();
+    } else {
+      nextRun = new Date(now.getTime() + this.#everyMs);
+    }
+    if (this.#from && nextRun < this.#from) {
+      if (this.#cronExpression) {
+        const cron = CronExpressionParser.parse(this.#cronExpression, {
+          currentDate: this.#from,
+          tz: this.#timezone
+        });
+        nextRun = cron.next().toDate();
+      } else {
+        nextRun = this.#from;
+      }
+    }
+    return nextRun;
+  }
+  /**
+   * Implement PromiseLike to allow `await builder.every('5m')` syntax.
+   */
+  then(onfulfilled, onrejected) {
+    return this.run().then(onfulfilled, onrejected);
+  }
+};
+
 // 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,
@@ -197,6 +405,34 @@ var Job = class {
     }
     return dispatcher;
   }
+  /**
+   * Create a schedule for this job.
+   *
+   * Returns a ScheduleBuilder for fluent configuration before creating the schedule.
+   * The schedule is not actually created until `.run()` is called or the
+   * builder is awaited.
+   *
+   * @param payload - The data to pass to the job on each run
+   * @returns A ScheduleBuilder for fluent configuration
+   *
+   * @example
+   * ```typescript
+   * // Cron schedule
+   * await CleanupJob.schedule({ days: 30 })
+   *   .id('cleanup-daily')
+   *   .cron('0 0 * * *')
+   *   .timezone('Europe/Paris')
+   *   .run()
+   *
+   * // Interval schedule
+   * await SyncJob.schedule({ source: 'api' })
+   *   .every('5m')
+   *   .run()
+   * ```
+   */
+  static schedule(payload) {
+    return new ScheduleBuilder(this.jobName, payload);
+  }
 };
 
 // src/worker.ts
@@ -206,18 +442,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 +495,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 +517,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 +568,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 +593,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 +609,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 +625,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 +661,59 @@ 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);
+        await this.#dispatchDueSchedules();
         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 +774,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 +826,193 @@ 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;
+    }
+  }
+  /**
+   * Dispatch any due scheduled jobs.
+   *
+   * Claims due schedules from the adapter and dispatches the corresponding
+   * jobs to their configured queues.
+   */
+  async #dispatchDueSchedules() {
+    while (true) {
+      const schedule = await this.#adapter.claimDueSchedule();
+      if (!schedule) {
+        break;
+      }
+      debug_default(
+        "worker %s: dispatching scheduled job %s (schedule: %s, runCount: %d)",
+        this.#id,
+        schedule.jobName,
+        schedule.id,
+        schedule.runCount + 1
+      );
+      const JobClass = Locator.get(schedule.jobName);
+      const queue = JobClass?.options?.queue ?? "default";
+      await this.#adapter.pushOn(queue, {
+        id: randomUUID2(),
+        name: schedule.jobName,
+        payload: schedule.payload,
+        attempts: 0,
+        priority: JobClass?.options?.priority
+      });
+    }
+  }
+};
+
+// src/schedule.ts
+var Schedule = class _Schedule {
+  #data;
+  constructor(data) {
+    this.#data = data;
+  }
+  get id() {
+    return this.#data.id;
+  }
+  get jobName() {
+    return this.#data.jobName;
+  }
+  get payload() {
+    return this.#data.payload;
+  }
+  get cronExpression() {
+    return this.#data.cronExpression;
+  }
+  get everyMs() {
+    return this.#data.everyMs;
+  }
+  get timezone() {
+    return this.#data.timezone;
+  }
+  get from() {
+    return this.#data.from;
+  }
+  get to() {
+    return this.#data.to;
+  }
+  get limit() {
+    return this.#data.limit;
+  }
+  get runCount() {
+    return this.#data.runCount;
+  }
+  get nextRunAt() {
+    return this.#data.nextRunAt;
+  }
+  get lastRunAt() {
+    return this.#data.lastRunAt;
+  }
+  get status() {
+    return this.#data.status;
+  }
+  get createdAt() {
+    return this.#data.createdAt;
+  }
+  /**
+   * Find a schedule by ID.
+   *
+   * @param id - The schedule ID
+   * @returns The schedule instance, or null if not found
+   */
+  static async find(id) {
+    const adapter = QueueManager.use();
+    const data = await adapter.getSchedule(id);
+    if (!data) return null;
+    return new _Schedule(data);
+  }
+  /**
+   * List all schedules matching the given options.
+   *
+   * @param options - Optional filters for listing
+   * @returns Array of schedule instances
+   */
+  static async list(options) {
+    const adapter = QueueManager.use();
+    const schedules = await adapter.listSchedules(options);
+    return schedules.map((data) => new _Schedule(data));
+  }
+  /**
+   * Pause this schedule.
+   * No jobs will be dispatched while paused.
+   */
+  async pause() {
+    const adapter = QueueManager.use();
+    await adapter.updateSchedule(this.#data.id, { status: "paused" });
+    this.#data.status = "paused";
+  }
+  /**
+   * Resume this schedule.
+   * Jobs will be dispatched according to the schedule.
+   */
+  async resume() {
+    const adapter = QueueManager.use();
+    await adapter.updateSchedule(this.#data.id, { status: "active" });
+    this.#data.status = "active";
+  }
+  /**
+   * Delete this schedule permanently.
+   */
+  async delete() {
+    const adapter = QueueManager.use();
+    await adapter.deleteSchedule(this.#data.id);
+  }
+  /**
+   * Trigger immediate execution of this schedule's job.
+   * Also updates runCount and lastRunAt.
+   *
+   * If the schedule has reached its limit, the job will not be dispatched.
+   */
+  async trigger() {
+    if (this.#data.limit !== null && this.#data.runCount >= this.#data.limit) {
+      return;
+    }
+    const adapter = QueueManager.use();
+    const dispatcher = new JobDispatcher(this.#data.jobName, this.#data.payload);
+    await dispatcher.run();
+    const now = /* @__PURE__ */ new Date();
+    const newRunCount = this.#data.runCount + 1;
+    await adapter.updateSchedule(this.#data.id, {
+      runCount: newRunCount,
+      lastRunAt: now
+    });
+    this.#data.runCount = newRunCount;
+    this.#data.lastRunAt = now;
   }
 };
 
@@ -458,10 +1021,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 +1075,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 +1163,13 @@ function customBackoff(config) {
 }
 export {
   Job,
+  Locator,
   QueueManager,
+  Schedule,
+  ScheduleBuilder,
   Worker,
   customBackoff,
+  exceptions_exports as errors,
   exponentialBackoff,
   fixedBackoff,
   linearBackoff