@boringnode/queue 0.4.0 → 0.5.0

package/build/chunk-WOUYSNK2.js

@@ -0,0 +1,128 @@
+import {
+  E_JOB_MAX_ATTEMPTS_REACHED,
+  E_JOB_TIMEOUT,
+  parse
+} from "./chunk-ZZFSQY36.js";
+
+// src/job_runtime.ts
+var JobExecutionRuntime = class _JobExecutionRuntime {
+  #jobName;
+  #options;
+  #retryConfig;
+  #timeout;
+  /**
+   * Build a runtime from already-resolved queue/job execution config.
+   */
+  static from({
+    jobName,
+    options,
+    retryConfig,
+    defaultTimeout
+  }) {
+    return new _JobExecutionRuntime({
+      jobName,
+      options,
+      retryConfig,
+      defaultTimeout
+    });
+  }
+  get maxRetries() {
+    return this.#retryConfig.maxRetries;
+  }
+  /**
+   * Create a runtime with fully resolved retry and timeout settings.
+   */
+  constructor({ jobName, options, retryConfig, defaultTimeout }) {
+    this.#jobName = jobName;
+    this.#options = options || {};
+    this.#retryConfig = retryConfig;
+    const timeout = this.#options.timeout ?? defaultTimeout;
+    this.#timeout = timeout === void 0 ? void 0 : parse(timeout);
+  }
+  /**
+   * Execute a hydrated job instance and enforce the configured timeout.
+   */
+  async execute(instance, payload, context) {
+    if (this.#timeout === void 0) {
+      instance.$hydrate(payload, context);
+      return instance.execute();
+    }
+    const signal = AbortSignal.timeout(this.#timeout);
+    instance.$hydrate(payload, context, signal);
+    const { abortPromise, cleanupAbortListener } = this.#createTimeoutAbortRace(
+      signal,
+      instance.constructor.name
+    );
+    try {
+      await Promise.race([instance.execute(), abortPromise]);
+    } finally {
+      cleanupAbortListener();
+    }
+  }
+  /**
+   * Convert an execution error into a retry or permanent-failure outcome.
+   */
+  resolveFailure(error, attempts) {
+    if (error instanceof E_JOB_TIMEOUT && this.#options.failOnTimeout) {
+      return {
+        type: "failed",
+        reason: "timeout",
+        storageError: error,
+        hookError: error
+      };
+    }
+    if (typeof this.#retryConfig.maxRetries === "undefined" || this.#retryConfig.maxRetries <= 0) {
+      return {
+        type: "failed",
+        reason: "no-retries",
+        storageError: error,
+        hookError: error
+      };
+    }
+    if (attempts >= this.#retryConfig.maxRetries) {
+      return {
+        type: "failed",
+        reason: "max-attempts",
+        storageError: error,
+        hookError: new E_JOB_MAX_ATTEMPTS_REACHED([this.#jobName], { cause: error })
+      };
+    }
+    if (this.#retryConfig.backoff) {
+      return {
+        type: "retry",
+        retryAt: this.#retryConfig.backoff().getNextRetryAt(attempts + 1)
+      };
+    }
+    return { type: "retry" };
+  }
+  /**
+   * Create the timeout race used to abort a job execution cleanly.
+   */
+  #createTimeoutAbortRace(signal, runtimeJobName) {
+    const timeout = this.#timeout;
+    let abortHandler;
+    const abortPromise = new Promise((_, reject) => {
+      abortHandler = () => {
+        reject(new E_JOB_TIMEOUT([runtimeJobName, timeout]));
+      };
+      if (signal.aborted) {
+        abortHandler();
+        return;
+      }
+      signal.addEventListener("abort", abortHandler, { once: true });
+    });
+    return {
+      abortPromise,
+      cleanupAbortListener: () => {
+        if (abortHandler) {
+          signal.removeEventListener("abort", abortHandler);
+        }
+      }
+    };
+  }
+};
+
+export {
+  JobExecutionRuntime
+};
+//# sourceMappingURL=chunk-WOUYSNK2.js.map

package/build/chunk-WOUYSNK2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/job_runtime.ts"],"sourcesContent":["import * as errors from './exceptions.js'\nimport type { Job } from './job.js'\nimport type { Duration, JobContext, JobOptions, RetryConfig } from './types/main.js'\nimport { parse } from './utils.js'\n\nexport type JobExecutionOutcome =\n  | { type: 'completed' }\n  | { type: 'retry'; retryAt?: Date }\n  | {\n      type: 'failed'\n      reason: 'timeout' | 'no-retries' | 'max-attempts'\n      storageError: Error\n      hookError: Error\n    }\n\ntype JobExecutionRuntimeConfig = {\n  jobName: string\n  options?: JobOptions\n  retryConfig: RetryConfig\n  defaultTimeout?: Duration\n}\n\ntype JobExecutionRuntimeFactoryOptions = {\n  jobName: string\n  options?: JobOptions\n  retryConfig: RetryConfig\n  defaultTimeout?: Duration\n}\n\n/**\n * Shared execution policy for a single job runtime.\n *\n * It encapsulates timeout resolution and retry/failure decisions so the\n * worker and the sync adapter follow the same execution rules.\n */\nexport class JobExecutionRuntime {\n  readonly #jobName: string\n  readonly #options: JobOptions\n  readonly #retryConfig: RetryConfig\n  readonly #timeout?: number\n\n  /**\n   * Build a runtime from already-resolved queue/job execution config.\n   */\n  static from({\n    jobName,\n    options,\n    retryConfig,\n    defaultTimeout,\n  }: JobExecutionRuntimeFactoryOptions): JobExecutionRuntime {\n    return new JobExecutionRuntime({\n      jobName,\n      options,\n      retryConfig,\n      defaultTimeout,\n    })\n  }\n\n  get maxRetries(): number | undefined {\n    return this.#retryConfig.maxRetries\n  }\n\n  /**\n   * Create a runtime with fully resolved retry and timeout settings.\n   */\n  constructor({ jobName, options, retryConfig, defaultTimeout }: JobExecutionRuntimeConfig) {\n    this.#jobName = jobName\n    this.#options = options || {}\n    this.#retryConfig = retryConfig\n\n    const timeout = this.#options.timeout ?? defaultTimeout\n    this.#timeout = timeout === undefined ? undefined : parse(timeout)\n  }\n\n  /**\n   * Execute a hydrated job instance and enforce the configured timeout.\n   */\n  async execute(instance: Job, payload: unknown, context: JobContext): Promise<void> {\n    if (this.#timeout === undefined) {\n      instance.$hydrate(payload, context)\n      return instance.execute()\n    }\n\n    const signal = AbortSignal.timeout(this.#timeout)\n    instance.$hydrate(payload, context, signal)\n\n    const { abortPromise, cleanupAbortListener } = this.#createTimeoutAbortRace(\n      signal,\n      instance.constructor.name\n    )\n\n    try {\n      await Promise.race([instance.execute(), abortPromise])\n    } finally {\n      cleanupAbortListener()\n    }\n  }\n\n  /**\n   * Convert an execution error into a retry or permanent-failure outcome.\n   */\n  resolveFailure(error: Error, attempts: number): JobExecutionOutcome {\n    if (error instanceof errors.E_JOB_TIMEOUT && this.#options.failOnTimeout) {\n      return {\n        type: 'failed',\n        reason: 'timeout',\n        storageError: error,\n        hookError: error,\n      }\n    }\n\n    if (typeof this.#retryConfig.maxRetries === 'undefined' || this.#retryConfig.maxRetries <= 0) {\n      return {\n        type: 'failed',\n        reason: 'no-retries',\n        storageError: error,\n        hookError: error,\n      }\n    }\n\n    if (attempts >= this.#retryConfig.maxRetries) {\n      return {\n        type: 'failed',\n        reason: 'max-attempts',\n        storageError: error,\n        hookError: new errors.E_JOB_MAX_ATTEMPTS_REACHED([this.#jobName], { cause: error }),\n      }\n    }\n\n    if (this.#retryConfig.backoff) {\n      return {\n        type: 'retry',\n        retryAt: this.#retryConfig.backoff().getNextRetryAt(attempts + 1),\n      }\n    }\n\n    return { type: 'retry' }\n  }\n\n  /**\n   * Create the timeout race used to abort a job execution cleanly.\n   */\n  #createTimeoutAbortRace(signal: AbortSignal, runtimeJobName: string) {\n    const timeout = this.#timeout!\n    let abortHandler: (() => void) | undefined\n\n    const abortPromise = new Promise<never>((_, reject) => {\n      abortHandler = () => {\n        reject(new errors.E_JOB_TIMEOUT([runtimeJobName, timeout]))\n      }\n\n      if (signal.aborted) {\n        abortHandler()\n        return\n      }\n\n      signal.addEventListener('abort', abortHandler, { once: true })\n    })\n\n    return {\n      abortPromise,\n      cleanupAbortListener: () => {\n        if (abortHandler) {\n          signal.removeEventListener('abort', abortHandler)\n        }\n      },\n    }\n  }\n}\n"],"mappings":";;;;;;;AAmCO,IAAM,sBAAN,MAAM,qBAAoB;AAAA,EACtB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA;AAAA;AAAA,EAKT,OAAO,KAAK;AAAA,IACV;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,GAA2D;AACzD,WAAO,IAAI,qBAAoB;AAAA,MAC7B;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AAAA,EACH;AAAA,EAEA,IAAI,aAAiC;AACnC,WAAO,KAAK,aAAa;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA,EAKA,YAAY,EAAE,SAAS,SAAS,aAAa,eAAe,GAA8B;AACxF,SAAK,WAAW;AAChB,SAAK,WAAW,WAAW,CAAC;AAC5B,SAAK,eAAe;AAEpB,UAAM,UAAU,KAAK,SAAS,WAAW;AACzC,SAAK,WAAW,YAAY,SAAY,SAAY,MAAM,OAAO;AAAA,EACnE;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,QAAQ,UAAe,SAAkB,SAAoC;AACjF,QAAI,KAAK,aAAa,QAAW;AAC/B,eAAS,SAAS,SAAS,OAAO;AAClC,aAAO,SAAS,QAAQ;AAAA,IAC1B;AAEA,UAAM,SAAS,YAAY,QAAQ,KAAK,QAAQ;AAChD,aAAS,SAAS,SAAS,SAAS,MAAM;AAE1C,UAAM,EAAE,cAAc,qBAAqB,IAAI,KAAK;AAAA,MAClD;AAAA,MACA,SAAS,YAAY;AAAA,IACvB;AAEA,QAAI;AACF,YAAM,QAAQ,KAAK,CAAC,SAAS,QAAQ,GAAG,YAAY,CAAC;AAAA,IACvD,UAAE;AACA,2BAAqB;AAAA,IACvB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,eAAe,OAAc,UAAuC;AAClE,QAAI,iBAAwB,iBAAiB,KAAK,SAAS,eAAe;AACxE,aAAO;AAAA,QACL,MAAM;AAAA,QACN,QAAQ;AAAA,QACR,cAAc;AAAA,QACd,WAAW;AAAA,MACb;AAAA,IACF;AAEA,QAAI,OAAO,KAAK,aAAa,eAAe,eAAe,KAAK,aAAa,cAAc,GAAG;AAC5F,aAAO;AAAA,QACL,MAAM;AAAA,QACN,QAAQ;AAAA,QACR,cAAc;AAAA,QACd,WAAW;AAAA,MACb;AAAA,IACF;AAEA,QAAI,YAAY,KAAK,aAAa,YAAY;AAC5C,aAAO;AAAA,QACL,MAAM;AAAA,QACN,QAAQ;AAAA,QACR,cAAc;AAAA,QACd,WAAW,IAAW,2BAA2B,CAAC,KAAK,QAAQ,GAAG,EAAE,OAAO,MAAM,CAAC;AAAA,MACpF;AAAA,IACF;AAEA,QAAI,KAAK,aAAa,SAAS;AAC7B,aAAO;AAAA,QACL,MAAM;AAAA,QACN,SAAS,KAAK,aAAa,QAAQ,EAAE,eAAe,WAAW,CAAC;AAAA,MAClE;AAAA,IACF;AAEA,WAAO,EAAE,MAAM,QAAQ;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA,EAKA,wBAAwB,QAAqB,gBAAwB;AACnE,UAAM,UAAU,KAAK;AACrB,QAAI;AAEJ,UAAM,eAAe,IAAI,QAAe,CAAC,GAAG,WAAW;AACrD,qBAAe,MAAM;AACnB,eAAO,IAAW,cAAc,CAAC,gBAAgB,OAAO,CAAC,CAAC;AAAA,MAC5D;AAEA,UAAI,OAAO,SAAS;AAClB,qBAAa;AACb;AAAA,MACF;AAEA,aAAO,iBAAiB,SAAS,cAAc,EAAE,MAAM,KAAK,CAAC;AAAA,IAC/D,CAAC;AAED,WAAO;AAAA,MACL;AAAA,MACA,sBAAsB,MAAM;AAC1B,YAAI,cAAc;AAChB,iBAAO,oBAAoB,SAAS,YAAY;AAAA,QAClD;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/build/{chunk-3BIR4IQD.js → chunk-ZZFSQY36.js}

@@ -21,7 +21,7 @@ __export(exceptions_exports, {
   E_NO_JOBS_FOUND: () => E_NO_JOBS_FOUND,
   E_QUEUE_NOT_INITIALIZED: () => E_QUEUE_NOT_INITIALIZED
 });
-import { createError } from "@poppinss/utils";
+import { createError } from "@poppinss/utils/exception";
 var E_INVALID_DURATION_EXPRESSION = createError(
   'Invalid duration expression: "%s"',
   "E_INVALID_DURATION_EXPRESSION",
@@ -144,4 +144,4 @@ export {
   parse,
   calculateScore
 };
-//# sourceMappingURL=chunk-3BIR4IQD.js.map
+//# sourceMappingURL=chunk-ZZFSQY36.js.map

package/build/chunk-ZZFSQY36.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/exceptions.ts","../src/constants.ts","../src/utils.ts"],"sourcesContent":["import { createError } from '@poppinss/utils/exception'\n\nexport const E_INVALID_DURATION_EXPRESSION = createError(\n  'Invalid duration expression: \"%s\"',\n  'E_INVALID_DURATION_EXPRESSION',\n  500\n)\n\nexport const E_INVALID_BASE_DELAY = createError<[reason: string]>(\n  'Invalid base delay. Reason: %s',\n  'E_INVALID_BASE_DELAY',\n  500\n)\n\nexport const E_INVALID_MAX_DELAY = createError<[reason: string]>(\n  'Invalid max delay. Reason: %s',\n  'E_INVALID_MAX_DELAY',\n  500\n)\n\nexport const E_INVALID_MULTIPLIER = createError<[reason: string]>(\n  'Invalid multiplier. Reason: %s',\n  'E_INVALID_MULTIPLIER',\n  500\n)\n\nexport const E_CONFIGURATION_ERROR = createError<[reason: string]>(\n  'Configuration error. Reason: %s',\n  'E_CONFIGURATION_ERROR',\n  500\n)\n\nexport const E_JOB_NOT_FOUND = createError<[jobName: string]>(\n  'Requested job \"%s\" is not registered',\n  'E_JOB_NOT_FOUND'\n)\n\nexport const E_JOB_MAX_ATTEMPTS_REACHED = createError<[jobName: string]>(\n  'The job \"%s\" has reached the maximum number of retry attempts',\n  'E_JOB_MAX_ATTEMPTS_REACHED'\n)\n\nexport const E_JOB_TIMEOUT = createError<[jobName: string, timeout: number]>(\n  'The job \"%s\" has exceeded the timeout of %dms',\n  'E_JOB_TIMEOUT'\n)\n\nexport const E_QUEUE_NOT_INITIALIZED = createError(\n  'QueueManager is not initialized. Call QueueManager.init() before using it.',\n  'E_QUEUE_NOT_INITIALIZED',\n  500\n)\n\nexport const E_ADAPTER_INIT_ERROR = createError<[adapterName: string, originalMessage: string]>(\n  'Failed to initialize adapter \"%s\". Reason: %s',\n  'E_ADAPTER_INIT_ERROR',\n  500\n)\n\nexport const E_NO_JOBS_FOUND = createError<[patterns: string]>(\n  'No jobs found for the specified locations: %s. Verify your glob patterns match your job files.',\n  'E_NO_JOBS_FOUND',\n  500\n)\n\nexport const E_INVALID_CRON_EXPRESSION = createError<[expression: string, reason: string]>(\n  'Invalid cron expression \"%s\": %s',\n  'E_INVALID_CRON_EXPRESSION',\n  500\n)\n\nexport const E_INVALID_SCHEDULE_CONFIG = createError<[reason: string]>(\n  'Invalid schedule configuration: %s',\n  'E_INVALID_SCHEDULE_CONFIG',\n  500\n)\n","/**\n * Default job priority (1-10 scale, lower = higher priority)\n */\nexport const DEFAULT_PRIORITY = 5\n\n/**\n * Multiplier used in score calculation: priority * multiplier + timestamp\n *\n * This ensures higher priority jobs are processed first,\n * while preserving FIFO order within the same priority.\n * The value (1e13) leaves room for ~300 years of millisecond timestamps.\n */\nexport const PRIORITY_SCORE_MULTIPLIER = 1e13\n\n/**\n * Default delay when the worker is idle (no jobs in queue)\n */\nexport const DEFAULT_IDLE_DELAY = '2s'\n\n/**\n * Default interval between stalled job checks\n */\nexport const DEFAULT_STALLED_INTERVAL = '30s'\n\n/**\n * Default threshold after which a job is considered stalled\n */\nexport const DEFAULT_STALLED_THRESHOLD = '30s'\n\n/**\n * Default delay before retrying after an error\n */\nexport const DEFAULT_ERROR_RETRY_DELAY = '5s'\n","import { parse as parseDuration } from '@lukeed/ms'\nimport type { Duration, JobRetention } from './types/main.js'\nimport * as errors from './exceptions.js'\nimport { PRIORITY_SCORE_MULTIPLIER } from './constants.js'\n\nexport interface ResolvedRetention {\n  keep: boolean\n  maxAge: number\n  maxCount: number\n}\n\nexport function resolveRetention(retention?: JobRetention): ResolvedRetention {\n  if (retention === undefined || retention === true) {\n    return { keep: false, maxAge: 0, maxCount: 0 }\n  }\n\n  if (retention === false) {\n    return { keep: true, maxAge: 0, maxCount: 0 }\n  }\n\n  return {\n    keep: true,\n    maxAge: retention.age ? parse(retention.age) : 0,\n    maxCount: retention.count ?? 0,\n  }\n}\n\nexport function parse(duration: Duration): number {\n  if (typeof duration === 'number') {\n    return duration\n  }\n\n  const milliseconds = parseDuration(duration)\n\n  if (typeof milliseconds === 'undefined') {\n    throw new errors.E_INVALID_DURATION_EXPRESSION([duration])\n  }\n\n  return milliseconds\n}\n\n/**\n * Calculate the score for job ordering in the queue.\n * Lower scores are processed first.\n *\n * @param priority - Job priority (1-10, lower = higher priority)\n * @param timestamp - Timestamp in milliseconds\n * @returns Score for queue ordering\n */\nexport function calculateScore(priority: number, timestamp: number): number {\n  return priority * PRIORITY_SCORE_MULTIPLIER + timestamp\n}\n"],"mappings":";;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,SAAS,mBAAmB;AAErB,IAAM,gCAAgC;AAAA,EAC3C;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,sBAAsB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,wBAAwB;AAAA,EACnC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,kBAAkB;AAAA,EAC7B;AAAA,EACA;AACF;AAEO,IAAM,6BAA6B;AAAA,EACxC;AAAA,EACA;AACF;AAEO,IAAM,gBAAgB;AAAA,EAC3B;AAAA,EACA;AACF;AAEO,IAAM,0BAA0B;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,kBAAkB;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,4BAA4B;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,4BAA4B;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AACF;;;ACxEO,IAAM,mBAAmB;AASzB,IAAM,4BAA4B;AAKlC,IAAM,qBAAqB;AAK3B,IAAM,2BAA2B;AAKjC,IAAM,4BAA4B;AAKlC,IAAM,4BAA4B;;;AChCzC,SAAS,SAAS,qBAAqB;AAWhC,SAAS,iBAAiB,WAA6C;AAC5E,MAAI,cAAc,UAAa,cAAc,MAAM;AACjD,WAAO,EAAE,MAAM,OAAO,QAAQ,GAAG,UAAU,EAAE;AAAA,EAC/C;AAEA,MAAI,cAAc,OAAO;AACvB,WAAO,EAAE,MAAM,MAAM,QAAQ,GAAG,UAAU,EAAE;AAAA,EAC9C;AAEA,SAAO;AAAA,IACL,MAAM;AAAA,IACN,QAAQ,UAAU,MAAM,MAAM,UAAU,GAAG,IAAI;AAAA,IAC/C,UAAU,UAAU,SAAS;AAAA,EAC/B;AACF;AAEO,SAAS,MAAM,UAA4B;AAChD,MAAI,OAAO,aAAa,UAAU;AAChC,WAAO;AAAA,EACT;AAEA,QAAM,eAAe,cAAc,QAAQ;AAE3C,MAAI,OAAO,iBAAiB,aAAa;AACvC,UAAM,IAAW,8BAA8B,CAAC,QAAQ,CAAC;AAAA,EAC3D;AAEA,SAAO;AACT;AAUO,SAAS,eAAe,UAAkB,WAA2B;AAC1E,SAAO,WAAW,4BAA4B;AAChD;","names":[]}

package/build/{index-CoubP-c4.d.ts → index-B1XdqWpN.d.ts}

@@ -411,7 +411,7 @@ interface JobContext {
  * The constructor accepts any arguments for dependency injection.
  * Payload and context are provided separately via `$hydrate()`.
  */
-type JobClass<T extends Job = Job> = (new (...args: any[]) => T) & {
+type JobClass<T extends Job = Job> = (new (...args: unknown[]) => T) & {
     options?: JobOptions;
 };
 /**
@@ -452,7 +452,7 @@ interface BackoffConfig {
 }
 interface QueueConfig {
     adapter?: string;
-    retry?: any;
+    retry?: RetryConfig;
     defaultJobOptions?: JobOptions;
 }
 interface WorkerConfig {
@@ -506,11 +506,11 @@ interface WorkerConfig {
 type WorkerCycle = {
     type: 'started';
     queue: string;
-    job: any;
+    job: JobData;
 } | {
     type: 'completed';
     queue: string;
-    job: any;
+    job: JobData;
 } | {
     type: 'idle';
     suggestedDelay: Duration;
@@ -796,6 +796,14 @@ interface Adapter {
      * @param config - The schedule configuration
      * @returns The schedule ID
      */
+    upsertSchedule(config: ScheduleConfig): Promise<string>;
+    /**
+     * Create or update a schedule.
+     *
+     * @deprecated Use `upsertSchedule` instead.
+     * @param config - The schedule configuration
+     * @returns The schedule ID
+     */
     createSchedule(config: ScheduleConfig): Promise<string>;
     /**
      * Get a schedule by ID.
@@ -987,7 +995,7 @@ declare class JobDispatcher<T> {
      * @param onRejected - Error callback
      * @returns Promise resolving to the DispatchResult
      */
-    then(onFulfilled?: (value: DispatchResult) => any, onRejected?: (reason: any) => any): Promise<any>;
+    then<TResult1 = DispatchResult, TResult2 = never>(onFulfilled?: ((value: DispatchResult) => TResult1 | PromiseLike<TResult1>) | null, onRejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
 }
 
 /**
@@ -1108,7 +1116,7 @@ declare class JobBatchDispatcher<T> {
      * @param onRejected - Error callback
      * @returns Promise resolving to the DispatchManyResult
      */
-    then(onFulfilled?: (value: DispatchManyResult) => any, onRejected?: (reason: any) => any): Promise<any>;
+    then<TResult1 = DispatchManyResult, TResult2 = never>(onFulfilled?: ((value: DispatchManyResult) => TResult1 | PromiseLike<TResult1>) | null, onRejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
 }
 
 /**
@@ -1129,9 +1137,9 @@ declare class JobBatchDispatcher<T> {
  *   .run()
  * ```
  */
-declare class ScheduleBuilder implements PromiseLike<ScheduleResult> {
+declare class ScheduleBuilder<TPayload = unknown> implements PromiseLike<ScheduleResult> {
     #private;
-    constructor(name: string, payload: any);
+    constructor(name: string, payload: TPayload);
     /**
      * Set a custom schedule ID.
      * If not specified, defaults to the job name.
@@ -1179,7 +1187,7 @@ declare class ScheduleBuilder implements PromiseLike<ScheduleResult> {
     /**
      * Implement PromiseLike to allow `await builder.every('5m')` syntax.
      */
-    then<TResult1 = ScheduleResult, TResult2 = never>(onfulfilled?: ((value: ScheduleResult) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    then<TResult1 = ScheduleResult, TResult2 = never>(onfulfilled?: ((value: ScheduleResult) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
 }
 
 /**
@@ -1331,7 +1339,7 @@ declare abstract class Job<Payload = any> {
      *   .run()
      * ```
      */
-    static dispatch<T extends Job>(this: new (...args: any[]) => T, payload: T extends Job<infer P> ? P : never): JobDispatcher<T extends Job<infer P> ? P : never>;
+    static dispatch<T extends Job>(this: abstract new (...args: any[]) => T, payload: T extends Job<infer P> ? P : never): JobDispatcher<T extends Job<infer P> ? P : never>;
     /**
      * Dispatch multiple jobs to the queue in a single batch.
      *
@@ -1359,7 +1367,7 @@ declare abstract class Job<Payload = any> {
      * console.log(`Dispatched ${jobIds.length} jobs`)
      * ```
      */
-    static dispatchMany<T extends Job>(this: new (...args: any[]) => T, payloads: (T extends Job<infer P> ? P : never)[]): JobBatchDispatcher<T extends Job<infer P> ? P : never>;
+    static dispatchMany<T extends Job>(this: abstract new (...args: any[]) => T, payloads: (T extends Job<infer P> ? P : never)[]): JobBatchDispatcher<T extends Job<infer P> ? P : never>;
     /**
      * Create a schedule for this job.
      *
@@ -1385,7 +1393,7 @@ declare abstract class Job<Payload = any> {
      *   .run()
      * ```
      */
-    static schedule<T extends Job>(this: new (...args: any[]) => T, payload: T extends Job<infer P> ? P : never): ScheduleBuilder;
+    static schedule<T extends Job>(this: abstract new (...args: any[]) => T, payload: T extends Job<infer P> ? P : never): ScheduleBuilder<T extends Job<infer P> ? P : never>;
     /**
      * Execute the job's business logic.
      *
@@ -1428,4 +1436,4 @@ declare abstract class Job<Payload = any> {
     failed?(error: Error): Promise<void>;
 }
 
-export { type Adapter as A, type BackoffStrategy as B, type Duration as D, type JobData as J, type Logger as L, type QueueManagerConfig as Q, type RetryConfig as R, type ScheduleConfig as S, type WorkerCycle as W, type JobClass as a, type AcquiredJob as b, type JobRetention as c, type JobRecord as d, type ScheduleData as e, type ScheduleListOptions as f, type JobFactory as g, type JobOptions as h, Job as i, type ScheduleStatus as j, ScheduleBuilder as k, JobBatchDispatcher as l, customBackoff as m, linearBackoff as n, exponentialBackoff as o, fixedBackoff as p, type JobStatus as q, type DispatchResult as r, type DispatchManyResult as s, type JobContext as t, type BackoffConfig as u, type QueueConfig as v, type WorkerConfig as w, type AdapterFactory as x, type ScheduleResult as y };
+export { type Adapter as A, type BackoffStrategy as B, type Duration as D, type JobData as J, type Logger as L, type QueueManagerConfig as Q, type RetryConfig as R, type ScheduleConfig as S, type WorkerCycle as W, type JobClass as a, type AcquiredJob as b, type JobRetention as c, type JobRecord as d, type ScheduleData as e, type ScheduleListOptions as f, type JobOptions as g, type QueueConfig as h, type JobFactory as i, Job as j, type ScheduleStatus as k, ScheduleBuilder as l, JobBatchDispatcher as m, customBackoff as n, linearBackoff as o, exponentialBackoff as p, fixedBackoff as q, type JobStatus as r, type DispatchResult as s, type DispatchManyResult as t, type JobContext as u, type BackoffConfig as v, type WorkerConfig as w, type AdapterFactory as x, type ScheduleResult as y };

package/build/index.d.ts

@@ -1,8 +1,8 @@
-import { Q as QueueManagerConfig, W as WorkerCycle, A as Adapter, R as RetryConfig, g as JobFactory, h as JobOptions, i as Job, a as JobClass, e as ScheduleData, j as ScheduleStatus, f as ScheduleListOptions } from './index-CoubP-c4.js';
-export { l as JobBatchDispatcher, k as ScheduleBuilder, m as customBackoff, o as exponentialBackoff, p as fixedBackoff, n as linearBackoff } from './index-CoubP-c4.js';
+import { Q as QueueManagerConfig, W as WorkerCycle, R as RetryConfig, g as JobOptions, h as QueueConfig, D as Duration, A as Adapter, i as JobFactory, L as Logger, j as Job, a as JobClass, e as ScheduleData, k as ScheduleStatus, f as ScheduleListOptions } from './index-B1XdqWpN.js';
+export { m as JobBatchDispatcher, l as ScheduleBuilder, n as customBackoff, p as exponentialBackoff, q as fixedBackoff, o as linearBackoff } from './index-B1XdqWpN.js';
 import { FakeAdapter } from './src/drivers/fake_adapter.js';
 import { Knex } from 'knex';
-import * as _poppinss_utils from '@poppinss/utils';
+import * as _poppinss_utils_exception from '@poppinss/utils/exception';
 
 /**
  * Job processing worker.
@@ -72,7 +72,8 @@ declare class Worker {
     /**
      * Stop the worker gracefully.
      *
-     * Waits for all running jobs to complete before shutting down.
+     * Waits for all running jobs to complete before stopping job consumption.
+     * Adapter cleanup remains the responsibility of `QueueManager.destroy()`.
      * Called automatically on SIGINT/SIGTERM if gracefulShutdown is enabled.
      */
     stop(): Promise<void>;
@@ -130,6 +131,42 @@ declare class Worker {
     process(queues: string[]): AsyncGenerator<WorkerCycle, void, unknown>;
 }
 
+/**
+ * Resolve effective queue/job runtime configuration from the initialized
+ * queue config.
+ *
+ * This keeps merge rules in one place without coupling execution code to the
+ * full `QueueManager` lifecycle and adapter concerns.
+ */
+declare class QueueConfigResolver {
+    #private;
+    /**
+     * Create a resolver from the queue manager config.
+     */
+    static from(config: QueueManagerConfig): QueueConfigResolver;
+    /**
+     * Create a resolver from already-materialized config fragments.
+     */
+    constructor({ globalRetryConfig, globalJobOptions, queueConfigs, workerTimeout, }: {
+        globalRetryConfig?: RetryConfig;
+        globalJobOptions?: JobOptions;
+        queueConfigs?: Map<string, QueueConfig>;
+        workerTimeout?: Duration;
+    });
+    /**
+     * Resolve the retry policy for a job using priority: job > queue > global.
+     */
+    resolveRetryConfig(queue: string, jobOptions?: JobOptions): RetryConfig;
+    /**
+     * Resolve effective retention options using priority: job > queue > global.
+     */
+    resolveJobOptions(queue: string, jobOptions?: JobOptions): JobOptions;
+    /**
+     * Return the configured default worker timeout.
+     */
+    getWorkerTimeout(): Duration | undefined;
+}
+
 /**
  * Central configuration and adapter management for the queue system.
  *
@@ -234,24 +271,6 @@ declare class QueueManagerSingleton {
      * Restore adapters after calling `fake()`.
      */
     restore(): void;
-    /**
-     * Get the merged retry configuration for a job.
-     *
-     * Configuration is merged with priority: job > queue > global.
-     * This allows specific jobs or queues to override global defaults.
-     *
-     * @param queue - The queue name
-     * @param jobRetryConfig - Optional job-level retry config
-     * @returns The merged retry configuration
-     *
-     * @example
-     * ```typescript
-     * // Global: maxRetries=3, Queue: maxRetries=5, Job: maxRetries=1
-     * // Result: maxRetries=1 (job wins)
-     * const config = QueueManager.getMergedRetryConfig('emails', { maxRetries: 1 })
-     * ```
-     */
-    getMergedRetryConfig(queue: string, jobRetryConfig?: RetryConfig): RetryConfig;
     /**
      * Get the configured job factory for custom instantiation.
      *
@@ -259,9 +278,13 @@ declare class QueueManagerSingleton {
      */
     getJobFactory(): JobFactory | undefined;
     /**
-     * Get the merged job options for a job (priority: job > queue > global).
+     * Get the configured logger used by the queue runtime.
+     */
+    getLogger(): Logger;
+    /**
+     * Get the resolver responsible for effective queue/job runtime config.
      */
-    getMergedJobOptions(queue: string, jobOptions?: JobOptions): JobOptions;
+    getConfigResolver(): QueueConfigResolver;
     /**
      * Clean up all adapter instances and reset state.
      *
@@ -399,7 +422,7 @@ declare class Schedule {
     constructor(data: ScheduleData);
     get id(): string;
     get name(): string;
-    get payload(): any;
+    get payload(): unknown;
     get cronExpression(): string | null;
     get everyMs(): number | null;
     get timezone(): string;
@@ -471,19 +494,19 @@ declare class QueueSchemaService {
     dropSchedulesTable(tableName?: string): Promise<void>;
 }
 
-declare const E_INVALID_DURATION_EXPRESSION: new (args?: any, options?: ErrorOptions) => _poppinss_utils.Exception;
-declare const E_INVALID_BASE_DELAY: new (args: [reason: string], options?: ErrorOptions) => _poppinss_utils.Exception;
-declare const E_INVALID_MAX_DELAY: new (args: [reason: string], options?: ErrorOptions) => _poppinss_utils.Exception;
-declare const E_INVALID_MULTIPLIER: new (args: [reason: string], options?: ErrorOptions) => _poppinss_utils.Exception;
-declare const E_CONFIGURATION_ERROR: new (args: [reason: string], options?: ErrorOptions) => _poppinss_utils.Exception;
-declare const E_JOB_NOT_FOUND: new (args: [jobName: string], options?: ErrorOptions) => _poppinss_utils.Exception;
-declare const E_JOB_MAX_ATTEMPTS_REACHED: new (args: [jobName: string], options?: ErrorOptions) => _poppinss_utils.Exception;
-declare const E_JOB_TIMEOUT: new (args: [jobName: string, timeout: number], options?: ErrorOptions) => _poppinss_utils.Exception;
-declare const E_QUEUE_NOT_INITIALIZED: new (args?: any, options?: ErrorOptions) => _poppinss_utils.Exception;
-declare const E_ADAPTER_INIT_ERROR: new (args: [adapterName: string, originalMessage: string], options?: ErrorOptions) => _poppinss_utils.Exception;
-declare const E_NO_JOBS_FOUND: new (args: [patterns: string], options?: ErrorOptions) => _poppinss_utils.Exception;
-declare const E_INVALID_CRON_EXPRESSION: new (args: [expression: string, reason: string], options?: ErrorOptions) => _poppinss_utils.Exception;
-declare const E_INVALID_SCHEDULE_CONFIG: new (args: [reason: string], options?: ErrorOptions) => _poppinss_utils.Exception;
+declare const E_INVALID_DURATION_EXPRESSION: new (args?: any, options?: ErrorOptions) => _poppinss_utils_exception.Exception;
+declare const E_INVALID_BASE_DELAY: new (args: [reason: string], options?: ErrorOptions) => _poppinss_utils_exception.Exception;
+declare const E_INVALID_MAX_DELAY: new (args: [reason: string], options?: ErrorOptions) => _poppinss_utils_exception.Exception;
+declare const E_INVALID_MULTIPLIER: new (args: [reason: string], options?: ErrorOptions) => _poppinss_utils_exception.Exception;
+declare const E_CONFIGURATION_ERROR: new (args: [reason: string], options?: ErrorOptions) => _poppinss_utils_exception.Exception;
+declare const E_JOB_NOT_FOUND: new (args: [jobName: string], options?: ErrorOptions) => _poppinss_utils_exception.Exception;
+declare const E_JOB_MAX_ATTEMPTS_REACHED: new (args: [jobName: string], options?: ErrorOptions) => _poppinss_utils_exception.Exception;
+declare const E_JOB_TIMEOUT: new (args: [jobName: string, timeout: number], options?: ErrorOptions) => _poppinss_utils_exception.Exception;
+declare const E_QUEUE_NOT_INITIALIZED: new (args?: any, options?: ErrorOptions) => _poppinss_utils_exception.Exception;
+declare const E_ADAPTER_INIT_ERROR: new (args: [adapterName: string, originalMessage: string], options?: ErrorOptions) => _poppinss_utils_exception.Exception;
+declare const E_NO_JOBS_FOUND: new (args: [patterns: string], options?: ErrorOptions) => _poppinss_utils_exception.Exception;
+declare const E_INVALID_CRON_EXPRESSION: new (args: [expression: string, reason: string], options?: ErrorOptions) => _poppinss_utils_exception.Exception;
+declare const E_INVALID_SCHEDULE_CONFIG: new (args: [reason: string], options?: ErrorOptions) => _poppinss_utils_exception.Exception;
 
 declare const exceptions_E_ADAPTER_INIT_ERROR: typeof E_ADAPTER_INIT_ERROR;
 declare const exceptions_E_CONFIGURATION_ERROR: typeof E_CONFIGURATION_ERROR;

package/build/index.js

@@ -1,3 +1,6 @@
+import {
+  JobExecutionRuntime
+} from "./chunk-WOUYSNK2.js";
 import {
   Job,
   JobBatchDispatcher,
@@ -6,7 +9,7 @@ import {
   QueueManager,
   ScheduleBuilder,
   debug_default
-} from "./chunk-H6WOFLPJ.js";
+} from "./chunk-OVYXMSSU.js";
 import {
   DEFAULT_ERROR_RETRY_DELAY,
   DEFAULT_IDLE_DELAY,
@@ -16,11 +19,9 @@ import {
   E_INVALID_BASE_DELAY,
   E_INVALID_MAX_DELAY,
   E_INVALID_MULTIPLIER,
-  E_JOB_MAX_ATTEMPTS_REACHED,
-  E_JOB_TIMEOUT,
   exceptions_exports,
   parse
-} from "./chunk-3BIR4IQD.js";
+} from "./chunk-ZZFSQY36.js";
 
 // src/worker.ts
 import { randomUUID } from "crypto";
@@ -199,7 +200,8 @@ var Worker = class {
   /**
    * Stop the worker gracefully.
    *
-   * Waits for all running jobs to complete before shutting down.
+   * Waits for all running jobs to complete before stopping job consumption.
+   * Adapter cleanup remains the responsibility of `QueueManager.destroy()`.
    * Called automatically on SIGINT/SIGTERM if gracefulShutdown is enabled.
    */
   async stop() {
@@ -209,9 +211,6 @@ var Worker = class {
       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();
   }
   /**
@@ -322,45 +321,48 @@ var Worker = class {
   async #execute(job, queue) {
     const startTime = performance.now();
     debug_default("worker %s: executing job %s (%s)", this.#id, job.id, job.name);
-    const { instance, options, timeout, context, payload } = await this.#initJob(job, queue);
-    const retention = QueueManager.getMergedJobOptions(queue, options);
+    const { instance, options, context, payload } = await this.#initJob(job, queue);
+    const configResolver = QueueManager.getConfigResolver();
+    const retention = configResolver.resolveJobOptions(queue, options);
+    const runtime = JobExecutionRuntime.from({
+      jobName: job.name,
+      options,
+      retryConfig: configResolver.resolveRetryConfig(queue, options),
+      defaultTimeout: configResolver.getWorkerTimeout()
+    });
     try {
-      await this.#executeWithTimeout(instance, payload, context, timeout);
+      await runtime.execute(instance, payload, context);
       await this.#adapter.completeJob(job.id, queue, retention.removeOnComplete);
       const duration = (performance.now() - startTime).toFixed(2);
       debug_default("worker %s: successfully executed job %s in %dms", this.#id, job.id, duration);
     } catch (e) {
-      const isTimeout = e instanceof E_JOB_TIMEOUT;
-      if (isTimeout && options.failOnTimeout) {
+      const outcome = runtime.resolveFailure(e, job.attempts);
+      if (outcome.type === "failed" && outcome.reason === "timeout") {
         debug_default("worker %s: job %s timed out and failOnTimeout is set", this.#id, job.id);
-        await this.#adapter.failJob(job.id, queue, e, retention.removeOnFail);
-        await instance.failed?.(e);
+        await this.#adapter.failJob(job.id, queue, outcome.storageError, retention.removeOnFail);
+        await instance.failed?.(outcome.hookError);
         return;
       }
-      const mergedConfig = QueueManager.getMergedRetryConfig(queue, options.retry);
-      if (typeof mergedConfig.maxRetries === "undefined" || mergedConfig.maxRetries <= 0) {
+      if (outcome.type === "failed" && outcome.reason === "no-retries") {
         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, retention.removeOnFail);
-        await instance.failed?.(e);
+        await this.#adapter.failJob(job.id, queue, outcome.storageError, retention.removeOnFail);
+        await instance.failed?.(outcome.hookError);
         return;
       }
-      if (job.attempts >= mergedConfig.maxRetries) {
+      if (outcome.type === "failed" && outcome.reason === "max-attempts") {
         debug_default(
           "worker %s: job %s has exceeded max retries (%d), marking as failed",
           this.#id,
           job.id,
-          mergedConfig.maxRetries
+          runtime.maxRetries
         );
-        await this.#adapter.failJob(job.id, queue, e, retention.removeOnFail);
-        const exception = new E_JOB_MAX_ATTEMPTS_REACHED([job.name], { cause: e });
-        await instance.failed?.(exception);
+        await this.#adapter.failJob(job.id, queue, outcome.storageError, retention.removeOnFail);
+        await instance.failed?.(outcome.hookError);
         return;
       }
-      if (mergedConfig.backoff) {
-        const strategy = mergedConfig.backoff();
-        const nextRetryAt = strategy.getNextRetryAt(job.attempts + 1);
-        debug_default("worker %s: job %s will retry at %s", this.#id, job.id, nextRetryAt.toISOString());
-        await this.#adapter.retryJob(job.id, queue, nextRetryAt);
+      if (outcome.type === "retry" && outcome.retryAt) {
+        debug_default("worker %s: job %s will retry at %s", this.#id, job.id, outcome.retryAt.toISOString());
+        await this.#adapter.retryJob(job.id, queue, outcome.retryAt);
         return;
       }
       await this.#adapter.retryJob(job.id, queue);
@@ -381,38 +383,14 @@ var Worker = class {
       const jobFactory = QueueManager.getJobFactory();
       const instance = jobFactory ? await jobFactory(JobClass) : new JobClass();
       const options = JobClass.options || {};
-      const timeout = this.#getJobTimeout(options);
-      return { instance, options, timeout, context, payload: job.payload };
+      return { instance, options, context, payload: job.payload };
     } catch (error) {
       debug_default("worker %s: failed to initialize job %s (%s)", this.#id, job.id, job.name);
-      const retention = QueueManager.getMergedJobOptions(queue);
+      const retention = QueueManager.getConfigResolver().resolveJobOptions(queue);
       await this.#adapter.failJob(job.id, queue, error, retention.removeOnFail);
       throw error;
     }
   }
-  #getJobTimeout(options) {
-    if (options.timeout !== void 0) {
-      return parse(options.timeout);
-    }
-    if (this.#config.worker?.timeout !== void 0) {
-      return parse(this.#config.worker.timeout);
-    }
-    return void 0;
-  }
-  async #executeWithTimeout(instance, payload, context, timeout) {
-    if (!timeout) {
-      instance.$hydrate(payload, context);
-      return instance.execute();
-    }
-    const signal = AbortSignal.timeout(timeout);
-    instance.$hydrate(payload, context, signal);
-    const abortPromise = new Promise((_, reject) => {
-      signal.addEventListener("abort", () => {
-        reject(new E_JOB_TIMEOUT([instance.constructor.name, timeout]));
-      });
-    });
-    await Promise.race([instance.execute(), abortPromise]);
-  }
   async #acquireNextJob(queues) {
     for (const queue of queues) {
       const job = await this.#adapter.popFrom(queue);
@@ -682,7 +660,7 @@ var QueueSchemaService = class {
 };
 
 // src/strategies/backoff_strategy.ts
-import { RuntimeException } from "@poppinss/utils";
+import { RuntimeException } from "@poppinss/utils/exception";
 import { assertUnreachable } from "@poppinss/utils/assert";
 var BackoffStrategy = class {
   #config;