@boringnode/queue 0.5.1 → 0.5.2

package/build/{job-DImdhRFO.d.ts → job-Z5fBSzRX.d.ts}

@@ -206,7 +206,13 @@ type Duration = number | string;
  * - `{ age?, count? }`: Keep with pruning by age and/or count
  */
 type JobRetention = boolean | {
+    /**
+     * Keep jobs newer than this duration.
+     */
     age?: Duration;
+    /**
+     * Keep at most this many jobs.
+     */
     count?: number;
 };
 /**
@@ -265,7 +271,7 @@ interface JobData {
     /**
      * Job priority (lower = higher priority).
      *
-     * @default 0
+     * @default 5
      */
     priority?: number;
     /**
@@ -291,6 +297,11 @@ interface JobData {
      * ```
      */
     groupId?: string;
+    /**
+     * Timestamp (ms) when the job was dispatched.
+     * Used to compute queue wait time in OTel instrumentation.
+     */
+    createdAt?: number;
     /**
      * Serialized trace context for distributed tracing.
      * Injected by OTel plugin at dispatch time.
@@ -345,22 +356,28 @@ interface JobOptions {
     queue?: string;
     /**
      * Adapter name or factory to use for this job.
+     *
+     * Defaults to the queue manager's configured default adapter.
      */
     adapter?: string | (() => Adapter);
     /**
      * Maximum retry attempts before permanent failure.
      *
-     * @default 3
+     * This is a convenience alias for `retry.maxRetries`.
+     *
+     * @default 0
      */
     maxRetries?: number;
     /**
      * Job priority (lower = higher priority).
      *
-     * @default 0
+     * @default 5
      */
     priority?: number;
     /**
-     * Retry configuration (backoff strategy, delays, etc.).
+     * Retry configuration for this job.
+     *
+     * Overrides queue-level and global retry settings.
      */
     retry?: RetryConfig;
     /**
@@ -372,10 +389,22 @@ interface JobOptions {
     /**
      * Whether to mark job as failed on timeout.
      *
-     * @default true
+     * When disabled, timed out jobs follow the normal retry policy.
+     *
+     * @default false
      */
     failOnTimeout?: boolean;
+    /**
+     * Retention policy for completed jobs.
+     *
+     * By default, completed jobs are removed immediately.
+     */
     removeOnComplete?: JobRetention;
+    /**
+     * Retention policy for failed jobs.
+     *
+     * By default, failed jobs are removed immediately after the failure hooks run.
+     */
     removeOnFail?: JobRetention;
 }
 /**
@@ -443,23 +472,77 @@ type JobClass<T extends Job = Job> = (new (...args: unknown[]) => T) & {
  * ```
  */
 type JobFactory = (JobClass: JobClass) => Job | Promise<Job>;
+/**
+ * Retry policy used by jobs, queues, or the queue manager.
+ */
 interface RetryConfig {
+    /**
+     * Number of retry attempts after the first failed execution.
+     *
+     * Set to `0` to disable retries.
+     *
+     * @default 0
+     */
     maxRetries?: number;
+    /**
+     * Factory that creates the backoff strategy used between retry attempts.
+     *
+     * If omitted, failed jobs are retried as soon as the adapter makes them
+     * available again.
+     */
     backoff?: () => BackoffStrategy$1;
 }
+/**
+ * Built-in retry delay algorithms.
+ */
 type BackoffStrategy = 'exponential' | 'linear' | 'fixed';
+/**
+ * Configuration for built-in and custom retry backoff strategies.
+ */
 interface BackoffConfig {
+    /**
+     * Strategy used to compute the delay before the next retry.
+     */
     strategy: BackoffStrategy;
+    /**
+     * Initial delay used by the strategy.
+     */
     baseDelay: Duration;
+    /**
+     * Upper bound for computed retry delays.
+     */
     maxDelay?: Duration;
+    /**
+     * Growth factor for exponential backoff.
+     */
     multiplier?: number;
+    /**
+     * Whether to randomize retry delays to avoid retry bursts.
+     */
     jitter?: boolean;
 }
+/**
+ * Runtime configuration for a named queue.
+ */
 interface QueueConfig {
+    /**
+     * Adapter name used by jobs dispatched to this queue.
+     *
+     * Falls back to the queue manager's default adapter.
+     */
     adapter?: string;
+    /**
+     * Retry policy applied to jobs in this queue unless overridden by job options.
+     */
     retry?: RetryConfig;
+    /**
+     * Default job options applied to jobs in this queue unless overridden by the job.
+     */
     defaultJobOptions?: JobOptions;
 }
+/**
+ * Runtime options for workers that poll queues and execute jobs.
+ */
 interface WorkerConfig {
     /**
      * Maximum number of jobs to process concurrently.
@@ -508,22 +591,32 @@ interface WorkerConfig {
      */
     onShutdownSignal?: () => void | Promise<void>;
 }
+/**
+ * Event yielded by the low-level worker processing generator.
+ */
 type WorkerCycle = {
+    /** A job was acquired and execution started. */
     type: 'started';
     queue: string;
     job: JobData;
 } | {
+    /** A running job finished, either successfully or after failure handling. */
     type: 'completed';
     queue: string;
     job: JobData;
 } | {
+    /** No work was available. Consumers should wait before polling again. */
     type: 'idle';
     suggestedDelay: Duration;
 } | {
+    /** An unexpected worker loop error occurred. */
     type: 'error';
     error: Error;
     suggestedDelay: Duration;
 };
+/**
+ * Factory used to lazily create adapter instances.
+ */
 type AdapterFactory<T extends Adapter = Adapter> = () => T;
 /**
  * Status of a schedule.
@@ -602,13 +695,59 @@ interface ScheduleListOptions {
     status?: ScheduleStatus;
 }
 interface QueueManagerConfig {
+    /**
+     * Name of the adapter used when a job does not select one explicitly.
+     *
+     * Must match one of the keys from `adapters`.
+     */
     default: string;
+    /**
+     * Available queue adapters keyed by name.
+     *
+     * Adapters are lazy-instantiated the first time they are used.
+     */
     adapters: Record<string, AdapterFactory>;
+    /**
+     * Global retry configuration applied to all jobs unless overridden by
+     * queue-level or job-level options.
+     */
     retry?: RetryConfig;
+    /**
+     * Global job options applied to all jobs unless overridden by queue-level
+     * or job-level options.
+     */
     defaultJobOptions?: JobOptions;
+    /**
+     * Per-queue configuration keyed by queue name.
+     *
+     * Use this to select adapters or defaults for specific queues.
+     */
     queues?: Record<string, QueueConfig>;
+    /**
+     * Worker runtime options used by `Worker` instances.
+     */
     worker?: WorkerConfig;
+    /**
+     * Glob patterns used to discover and register job classes.
+     *
+     * These locations are used by `init()` when `autoLoadJobs` is enabled,
+     * and by `QueueManager.loadJobs()` when called without arguments.
+     */
     locations?: string[];
+    /**
+     * Whether `init()` should immediately register jobs from configured locations.
+     *
+     * Framework integrations may disable this to defer job loading until a
+     * command lifecycle is ready, then call `QueueManager.loadJobs()`.
+     *
+     * @default true
+     */
+    autoLoadJobs?: boolean;
+    /**
+     * Logger used by the queue runtime.
+     *
+     * Defaults to the console logger.
+     */
     logger?: Logger;
     /**
      * Custom factory function for job instantiation.

package/build/src/contracts/adapter.d.ts

@@ -1 +1 @@
-export { b as AcquiredJob, A as Adapter } from '../../job-DImdhRFO.js';
+export { b as AcquiredJob, A as Adapter } from '../../job-Z5fBSzRX.js';

package/build/src/drivers/fake_adapter.d.ts

@@ -1,4 +1,4 @@
-import { A as Adapter, J as JobData, a as JobClass, b as AcquiredJob, c as JobRetention, d as JobRecord, S as ScheduleConfig, e as ScheduleData, f as ScheduleListOptions } from '../../job-DImdhRFO.js';
+import { A as Adapter, J as JobData, a as JobClass, b as AcquiredJob, c as JobRetention, d as JobRecord, S as ScheduleConfig, e as ScheduleData, f as ScheduleListOptions } from '../../job-Z5fBSzRX.js';
 
 interface FakeJobRecord {
     queue: string;
@@ -23,6 +23,11 @@ declare function fake(): () => FakeAdapter;
  */
 declare class FakeAdapter implements Adapter {
     #private;
+    /**
+     * Set the function to call when the fake is disposed
+     */
+    onDispose(fn: () => void): this;
+    [Symbol.dispose](): void;
     setWorkerId(_workerId: string): void;
     getPushedJobs(): FakeJobRecord[];
     getPushedJobsOn(queue: string): FakeJobRecord[];

package/build/src/drivers/fake_adapter.js

@@ -1,7 +1,7 @@
 import {
   FakeAdapter,
   fake
-} from "../../chunk-VHN3XZDC.js";
+} from "../../chunk-VRXHCWNK.js";
 import "../../chunk-WVLSICD4.js";
 import "../../chunk-QEFYHCL7.js";
 import "../../chunk-PZ5AY32C.js";

package/build/src/drivers/knex_adapter.d.ts

@@ -1,5 +1,5 @@
 import { Knex } from 'knex';
-import { A as Adapter, b as AcquiredJob, c as JobRetention, d as JobRecord, J as JobData, S as ScheduleConfig, e as ScheduleData, f as ScheduleListOptions } from '../../job-DImdhRFO.js';
+import { A as Adapter, b as AcquiredJob, c as JobRetention, d as JobRecord, J as JobData, S as ScheduleConfig, e as ScheduleData, f as ScheduleListOptions } from '../../job-Z5fBSzRX.js';
 
 interface KnexAdapterOptions {
     connection: Knex;

package/build/src/drivers/redis_adapter.d.ts

@@ -1,5 +1,5 @@
 import { Redis, RedisOptions } from 'ioredis';
-import { A as Adapter, b as AcquiredJob, c as JobRetention, d as JobRecord, J as JobData, S as ScheduleConfig, e as ScheduleData, f as ScheduleListOptions } from '../../job-DImdhRFO.js';
+import { A as Adapter, b as AcquiredJob, c as JobRetention, d as JobRecord, J as JobData, S as ScheduleConfig, e as ScheduleData, f as ScheduleListOptions } from '../../job-Z5fBSzRX.js';
 
 type RedisConfig = Redis | RedisOptions;
 /**

package/build/src/drivers/redis_adapter.js

@@ -298,73 +298,71 @@ var GET_JOB_SCRIPT = `
   })
 `;
 var CLAIM_SCHEDULE_SCRIPT = `
-  local schedule_key = KEYS[1]
+  local schedules_index_key = KEYS[1]
+  local schedule_key_prefix = KEYS[2]
   local now = tonumber(ARGV[1])
 
-  -- Get schedule data
-  local data = redis.call('HGETALL', schedule_key)
-  if #data == 0 then
-    return nil
-  end
-
-  -- Convert HGETALL result to table
-  local schedule = {}
-  for j = 1, #data, 2 do
-    schedule[data[j]] = data[j + 1]
-  end
-
-  -- Check if schedule is due
-  if schedule.status ~= 'active' then
-    return nil
-  end
-
-  local next_run_at = tonumber(schedule.next_run_at)
-  if not next_run_at or next_run_at > now then
-    return nil
-  end
+  local ids = redis.call('SMEMBERS', schedules_index_key)
 
-  local run_count = tonumber(schedule.run_count or '0')
-  local run_limit = schedule.run_limit and tonumber(schedule.run_limit) or nil
-  local to_date = schedule.to_date and tonumber(schedule.to_date) or nil
+  for i = 1, #ids do
+    local schedule_key = schedule_key_prefix .. ids[i]
 
-  -- Check limits
-  if run_limit and run_count >= run_limit then
-    return nil
-  end
-
-  if to_date and now > to_date then
-    return nil
-  end
-
-  -- This schedule is claimable - atomically update it
-  local new_run_count = run_count + 1
-
-  -- Calculate new next_run_at (simple interval-based for now)
-  -- Complex cron calculation happens in the caller
-  local new_next_run_at = ''
-  local every_ms = schedule.every_ms and tonumber(schedule.every_ms) or nil
-  if every_ms then
-    new_next_run_at = tostring(now + every_ms)
-  end
-
-  -- Check if we've hit the limit after this run
-  if run_limit and new_run_count >= run_limit then
-    new_next_run_at = ''
-  end
+    -- Get schedule data
+    local data = redis.call('HGETALL', schedule_key)
+    if #data > 0 then
+      -- Convert HGETALL result to table
+      local schedule = {}
+      for j = 1, #data, 2 do
+        schedule[data[j]] = data[j + 1]
+      end
 
-  -- Check if past end date
-  if to_date and new_next_run_at ~= '' and tonumber(new_next_run_at) > to_date then
-    new_next_run_at = ''
+      -- Check if schedule is due
+      if schedule.status == 'active' then
+        local next_run_at = tonumber(schedule.next_run_at)
+
+        if next_run_at and next_run_at <= now then
+          local run_count = tonumber(schedule.run_count or '0')
+          local run_limit = schedule.run_limit and tonumber(schedule.run_limit) or nil
+          local to_date = schedule.to_date and tonumber(schedule.to_date) or nil
+
+          -- Check limits
+          if not (run_limit and run_count >= run_limit) and not (to_date and now > to_date) then
+            -- This schedule is claimable - atomically update it
+            local new_run_count = run_count + 1
+
+            -- Calculate new next_run_at (simple interval-based for now)
+            -- Complex cron calculation happens in the caller
+            local new_next_run_at = ''
+            local every_ms = schedule.every_ms and tonumber(schedule.every_ms) or nil
+            if every_ms then
+              new_next_run_at = tostring(now + every_ms)
+            end
+
+            -- Check if we've hit the limit after this run
+            if run_limit and new_run_count >= run_limit then
+              new_next_run_at = ''
+            end
+
+            -- Check if past end date
+            if to_date and new_next_run_at ~= '' and tonumber(new_next_run_at) > to_date then
+              new_next_run_at = ''
+            end
+
+            -- Update the schedule atomically
+            redis.call('HSET', schedule_key,
+              'next_run_at', new_next_run_at,
+              'last_run_at', tostring(now),
+              'run_count', tostring(new_run_count))
+
+            -- Return the schedule data (before update) as JSON
+            return cjson.encode(schedule)
+          end
+        end
+      end
+    end
   end
 
-  -- Update the schedule atomically
-  redis.call('HSET', schedule_key,
-    'next_run_at', new_next_run_at,
-    'last_run_at', tostring(now),
-    'run_count', tostring(new_run_count))
-
-  -- Return the schedule data (before update) as JSON
-  return cjson.encode(schedule)
+  return nil
 `;
 function redis(config) {
   return () => {
@@ -665,40 +663,40 @@ var RedisAdapter = class {
   }
   async claimDueSchedule() {
     const now = Date.now();
-    const ids = await this.#connection.smembers(schedulesIndexKey);
-    for (const id of ids) {
-      const scheduleKey = `${schedulesKey}::${id}`;
-      const result = await this.#connection.eval(
-        CLAIM_SCHEDULE_SCRIPT,
-        1,
-        scheduleKey,
-        now.toString()
-      );
-      if (!result) {
-        continue;
-      }
-      const data = JSON.parse(result);
-      if (data.cron_expression) {
-        const { CronExpressionParser } = await import("cron-parser");
-        const cron = CronExpressionParser.parse(data.cron_expression, {
-          currentDate: new Date(now),
-          tz: data.timezone || "UTC"
-        });
-        const nextRun = cron.next().toDate().getTime();
-        const runCount = Number.parseInt(data.run_count || "0", 10) + 1;
-        const runLimit = data.run_limit ? Number.parseInt(data.run_limit, 10) : null;
-        const toDate = data.to_date ? Number.parseInt(data.to_date, 10) : null;
-        let newNextRunAt = nextRun;
-        if (runLimit !== null && runCount >= runLimit) {
-          newNextRunAt = "";
-        } else if (toDate && nextRun > toDate) {
-          newNextRunAt = "";
-        }
-        await this.#connection.hset(scheduleKey, "next_run_at", newNextRunAt.toString());
+    const result = await this.#connection.eval(
+      CLAIM_SCHEDULE_SCRIPT,
+      2,
+      schedulesIndexKey,
+      `${schedulesKey}::`,
+      now.toString()
+    );
+    if (!result) {
+      return null;
+    }
+    const data = JSON.parse(result);
+    if (data.cron_expression) {
+      const { CronExpressionParser } = await import("cron-parser");
+      const cron = CronExpressionParser.parse(data.cron_expression, {
+        currentDate: new Date(now),
+        tz: data.timezone || "UTC"
+      });
+      const nextRun = cron.next().toDate().getTime();
+      const runCount = Number.parseInt(data.run_count || "0", 10) + 1;
+      const runLimit = data.run_limit ? Number.parseInt(data.run_limit, 10) : null;
+      const toDate = data.to_date ? Number.parseInt(data.to_date, 10) : null;
+      let newNextRunAt = nextRun;
+      if (runLimit !== null && runCount >= runLimit) {
+        newNextRunAt = "";
+      } else if (toDate && nextRun > toDate) {
+        newNextRunAt = "";
       }
-      return this.#hashToScheduleData(data);
+      await this.#connection.hset(
+        `${schedulesKey}::${data.id}`,
+        "next_run_at",
+        newNextRunAt.toString()
+      );
     }
-    return null;
+    return this.#hashToScheduleData(data);
   }
   #hashToScheduleData(data) {
     return {