@bymax-one/nest-queue 1.2.13 → 1.2.15

package/dist/server/index.d.cts

@@ -58,7 +58,10 @@ interface BymaxQueueModuleOptions {
     connection: QueueConnectionConfig;
     /** Default options applied to every job enqueued through the service. */
     defaultJobOptions?: JobsOptions;
-    /** Prefix for all Redis keys (multi-tenant isolation). Default: 'bull'. */
+    /**
+     * Prefix for all Redis keys, a namespace and not an access control: anything that can reach the
+     * Redis instance can read every prefix on it. Default: 'bull'.
+     */
     prefix?: string;
     /** Default options applied to every Queue, merged with the job/prefix defaults. */
     queueOptions?: Partial<Omit<QueueOptions, 'connection' | 'defaultJobOptions' | 'prefix'>>;
@@ -87,8 +90,28 @@ interface BymaxQueueModuleOptions {
      * Default: true.
      */
     isGlobal?: boolean;
-    /** Mode B only: milliseconds to wait for Redis `ready` before throwing. Default: 10_000. */
+    /**
+     * Mode B only: the startup budget, in milliseconds, for Redis to reach `ready`. Connection errors
+     * while the client is still reconnecting do not end the wait; the budget does, with
+     * `CONNECTION_TIMEOUT`, and the client the library opened is closed. Default: 10_000.
+     */
     connectionReadyTimeoutMs?: number;
+    /**
+     * Mode B only: the deadline, in milliseconds, for one Redis command on the connection the library
+     * opened (ioredis `commandTimeout`). A command that gets no reply in time rejects instead of
+     * waiting out ioredis' own retry window. An `options.commandTimeout` in the connection config
+     * wins. Worker and QueueEvents connections never inherit it, because they block by design.
+     * Default: 5_000.
+     */
+    commandTimeoutMs?: number;
+    /**
+     * The deadline, in milliseconds, for one `QueueService` call that reaches Redis (`enqueue`,
+     * `getJob`, `getMetrics`, the scheduler, pause and clean calls, and the rest) in either connection
+     * mode, including the wait for the client to be ready on a queue's first call. When it passes, the
+     * call rejects with `CONNECTION_TIMEOUT`; an `enqueue` may still complete in Redis afterwards, so
+     * retry with a stable `jobId` or `deduplication`. Default: 10_000.
+     */
+    enqueueTimeoutMs?: number;
 }
 /** A factory that produces module options, for async configuration. */
 interface BymaxQueueOptionsFactory {
@@ -236,6 +259,10 @@ interface ResolvedQueueOptions {
     telemetry?: Telemetry;
     /** Mode B ready timeout in milliseconds. */
     connectionReadyTimeoutMs: number;
+    /** Mode B per-command deadline in milliseconds. */
+    commandTimeoutMs: number;
+    /** Deadline in milliseconds for one enqueue call. */
+    enqueueTimeoutMs: number;
 }
 
 /**
@@ -362,7 +389,9 @@ declare class ConnectionResolver {
     /**
      * Merge the consumer's options with the owned-connection policy
      * (`lazyConnect: false`, so the client connects eagerly and `init` can wait
-     * for `ready`) and narrow the result to the shape ioredis 6's constructor
+     * for `ready`; a command deadline, so a frozen Redis fails a call in seconds; and no offline
+     * queue, so a call made during an outage fails at once instead of buffering without bound —
+     * each only where the consumer has not chosen a value) and narrow the result to the shape ioredis 6's constructor
      * accepts. The runtime object is unchanged — the cast only drops the
      * `undefined` that `RedisOptions.replyMapping` carries and the constructor
      * rejects.
@@ -374,11 +403,26 @@ declare class ConnectionResolver {
     getMode(): QueueConnectionMode;
     /** Whether the library owns (and must close) the connection. */
     isOwned(): boolean;
+    /**
+     * Settle when the client can take a command. While it is still connecting or reconnecting, every
+     * caller shares one wait on its `ready` event, so a health check that polls through a long outage
+     * adds one listener set to the client, not one per call, and gives it back when Redis returns. A
+     * lazy client (`wait`) connects on its first command and a finished one (`end`) never becomes
+     * ready, so both are left for the call itself.
+     */
+    awaitReady(): Promise<void>;
     /** Close the library-owned connection on shutdown; never touch a BYO client. */
     teardown(): Promise<void>;
     /** Validate and adopt a bring-your-own client for the Queue role. */
     private initModeA;
-    /** Resolve when the owned client reaches `ready`, or reject on timeout/error. */
+    /**
+     * Resolve when the owned client reaches `ready`. A connection error while the client is still
+     * reconnecting does not end the wait — a Redis that restarts during a deploy refuses connections
+     * for a moment first — so the budget does. The two exceptions are an answer from the server that
+     * waiting cannot change (a refused credential) and a client that has stopped reconnecting; both
+     * reject at once. The rejection carries the last error's code and never its message, which can
+     * name the host.
+     */
     private waitReady;
 }
 
@@ -412,13 +456,27 @@ declare class QueueService {
      * @param overrides - Optional per-queue option overrides.
      */
     getOrCreateQueue<TData = unknown, TResult = unknown>(queueName: string, overrides?: Partial<Omit<QueueOptions, 'connection' | 'prefix'>>): Queue<TData, TResult>;
+    /**
+     * Run one Redis call under the per-call deadline (`enqueueTimeoutMs`), reporting every way Redis
+     * can fail to answer as the documented `CONNECTION_TIMEOUT`: the deadline passing, an ioredis
+     * command timeout, or a call refused because the connection is down.
+     *
+     * The first call on a queue name waits for the client to be ready through ONE wait shared by all
+     * callers, instead of letting BullMQ start its own unbounded wait per call, so a caller that
+     * polls through an outage does not pile up listeners. The call runs only if it is still within
+     * its deadline when the client is ready; a caller that was told it timed out never has its call
+     * run later, which would turn its retry into a duplicate.
+     */
+    private call;
+    /** Settle when a call on `queueName` may start: at once for a queue that has been used before. */
+    private afterReady;
     /** Resolve the raw cached queue (default generics) for internal delegation. */
     private queueFor;
     /**
      * Add a single job to a queue. The queue is created lazily if needed.
      *
      * Delivery is **at-least-once** — a handler may run more than once for the same
-     * job (worker crash, lock expiry, or a shutdown force-close). Make handlers
+     * job (worker crash, lock expiry, or a shutdown that outlasts the drain budget). Make handlers
      * idempotent: use an idempotency key on writes, prefer upserts over inserts, or
      * keep an "already-processed" marker keyed by `job.id`.
      *
@@ -492,7 +550,9 @@ declare class QueueService {
      * @param queueName - Target queue.
      * @param status - Status filter.
      * @param start - Starting index (inclusive). Default: 0.
-     * @param end - Ending index (inclusive). Default: 50.
+     * @param end - Ending index (inclusive). Default: 50. The window may span at most
+     *   `MAX_JOBS_PAGE_SIZE` (1000) jobs, and BullMQ's `-1` (everything) is refused.
+     * @throws {QueueException} `INVALID_OPTIONS` when the window is not a bounded range of integers.
      */
     getJobs<TData = unknown, TResult = unknown>(queueName: string, status: JobStatus, start?: number, end?: number): Promise<TypedJob<TData, TResult>[]>;
     /**
@@ -597,6 +657,7 @@ declare class QueueService {
  * })
  */
 declare class FlowService {
+    #private;
     private readonly logger;
     private readonly producer?;
     constructor(connection: ConnectionResolver, enabled: boolean, prefix: string, telemetry?: Telemetry);
@@ -629,6 +690,8 @@ declare class FlowService {
      * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled.
      */
     addBulk(flows: readonly FlowJob[]): Promise<JobNode[]>;
+    /** The command deadline of the producer connection, read when a command has timed out. */
+    private commandTimeout;
     /**
      * Escape hatch returning the underlying `FlowProducer` for advanced use cases.
      * Prefer {@link FlowService.add} / {@link FlowService.addBulk} when possible.
@@ -751,6 +814,14 @@ interface WorkerOptions {
     lockDuration?: number;
     /** Interval between stalled-job checks, in milliseconds. Default: 30_000. */
     stalledInterval?: number;
+    /**
+     * Fail a job whose handler has not settled after this many milliseconds, so it retries under the
+     * job's `attempts` and `backoff` and its concurrency slot is freed. The handler's `signal` aborts
+     * at that moment; a handler that ignores it keeps running in the background. There is no default:
+     * without it a handler that never settles holds its slot indefinitely. Not available for
+     * sandboxed workers. Range: 1 to 2_147_483_647.
+     */
+    jobTimeoutMs?: number;
 }
 
 /**
@@ -773,8 +844,13 @@ interface WorkerOptions {
 interface ProgrammaticWorkerConfig<TData = unknown, TResult = unknown> {
     /** BullMQ queue the worker should consume. */
     queueName: string;
-    /** Async function that processes a single job. Must be idempotent. */
-    handler: (job: Job<TData, TResult>) => Promise<TResult>;
+    /**
+     * Async function that processes a single job. Must be idempotent. Its optional second argument
+     * is the job's `AbortSignal`: it aborts when the job's `jobTimeoutMs` passes or when BullMQ
+     * cancels the job (`worker.cancelJob()`, `worker.cancelAllJobs()`). Closing the worker does not
+     * abort it. Pass it to whatever the handler awaits so the work stops with the job.
+     */
+    handler: (job: Job<TData, TResult>, signal?: AbortSignal) => Promise<TResult>;
     /** Optional worker tuning overrides. */
     options?: WorkerOptions;
 }
@@ -912,6 +988,14 @@ declare class WorkerRegistry {
      * @throws {QueueException} `WORKER_REGISTRATION_FAILED` when values are out of range.
      */
     private validateOptions;
+    /**
+     * Validate `jobTimeoutMs`, which must be a timer delay Node honours: above 2^31 - 1 ms it would
+     * fire after 1 ms and fail every job at once.
+     *
+     * @param opts - The caller-supplied options (may be undefined).
+     * @throws {QueueException} `WORKER_REGISTRATION_FAILED` when the value is out of range.
+     */
+    private validateJobTimeout;
     /**
      * Validate that `processorFile` is a safe, reachable artifact path. Accepts
      * absolute paths with `.js`/`.cjs`/`.mjs` extensions and `file:` URLs. Rejects
@@ -1020,9 +1104,9 @@ declare class QueueEventsRegistry {
  * HTTP server has stopped, it releases what a request can still be using: the
  * flow producer, the cached queues, and finally the Queue-role connection.
  *
- * Delivery is at-least-once: when a worker exceeds the drain budget it is
- * force-closed and its in-flight job becomes `stalled` and is retried by another
- * worker. Handlers must therefore be idempotent, and `lockDuration` should
+ * Delivery is at-least-once: when a worker exceeds the drain budget it is stopped
+ * without waiting for its job, whose lock then expires so the job becomes `stalled`
+ * and is retried by another worker. Handlers must therefore be idempotent, and `lockDuration` should
  * comfortably exceed the worst-case handler runtime so healthy long jobs are
  * never treated as stalled.
  * @layer server/lifecycle
@@ -1071,28 +1155,26 @@ declare class QueueLifecycle implements OnModuleDestroy, OnApplicationShutdown {
      */
     onApplicationShutdown(): Promise<void>;
     /**
-     * Close every worker with a bounded drain, force-closing any that exceed the
-     * budget. Returns the number of workers that had to be force-closed.
+     * Stop every worker in parallel, each bounded by what is left of the shutdown budget. A worker
+     * is paused first (it stops fetching and waits for its active jobs) and then closed. One that is
+     * still busy when the budget ends is closed with `close(true)`: because `pause` does not start a
+     * close, that is the worker's FIRST close, so it does not wait for the job and stops the lock
+     * renewal that would otherwise keep running and keep the process alive. The job's lock then
+     * expires, and it stalls and is retried elsewhere. Returns how many workers were stopped
+     * without draining.
      *
-     * @returns The count of force-closed workers.
+     * @param deadline - The epoch millisecond at which the shutdown budget ends.
+     * @returns The count of workers stopped without draining.
      */
     private closeWorkers;
-    /**
-     * Race a graceful `worker.close()` against a timer. `worker.close()` already
-     * drains active jobs and takes no timeout argument, so the timer is the only
-     * way to bound the wait. Rejects with a timeout error when the budget elapses.
-     *
-     * @param worker - The worker to close.
-     * @param timeoutMs - The drain budget in milliseconds.
-     */
-    private closeWorkerWithTimeout;
-    /** Close every cached `QueueEvents`, swallowing individual failures. */
+    /** Close every cached `QueueEvents` in parallel within the budget, swallowing failures. */
     private closeQueueEvents;
     /**
-     * Close the duplicated worker/queue-events connections the library opened.
-     * BullMQ treats a passed-in client as shared and never closes it, so the
-     * library must release these explicitly. In Mode A the consumer's shared
-     * client is never among them.
+     * Close the duplicated worker/queue-events connections the library opened, in parallel. BullMQ
+     * treats a passed-in client as shared and never closes it, so the library must release these
+     * explicitly. A connection that does not quit within the budget is disconnected, which also
+     * releases anything still blocked on it. In Mode A the consumer's shared client is never among
+     * them.
      */
     private closeDuplicatedConnections;
     /**
@@ -1161,7 +1243,7 @@ declare function Processor(queueName: string, options?: WorkerOptions): ClassDec
  * an entry to the accumulated metadata array.
  *
  * Delivery is at-least-once: a handler may run more than once for the same job
- * (worker crash, lock expiry, or a shutdown force-close). Handlers MUST be
+ * (worker crash, lock expiry, or a shutdown that outlasts the drain budget). Handlers MUST be
  * idempotent — use an idempotency key on writes, prefer upserts over inserts, or
  * keep an "already-processed" marker keyed by `job.id`.
  *
@@ -1213,7 +1295,7 @@ type WorkerEventName = 'completed' | 'failed' | 'progress' | 'active' | 'stalled
  * overwriting each other.
  *
  * Delivery is at-least-once. A `'stalled'` job — for example after a shutdown
- * force-close or a lock expiry — is re-run by another worker: this is the
+ * that outlasts the drain budget, or a lock expiry — is re-run by another worker: this is the
  * visible at-least-once path, so handlers must be idempotent. Set `lockDuration`
  * comfortably above the worst-case handler runtime to avoid false stalls.
  *
@@ -1408,13 +1490,16 @@ declare const DEFAULT_WORKER_CONCURRENCY: 2;
 declare const MAX_WORKER_CONCURRENCY: 1000;
 /**
  * Default options applied to every job enqueued through the service. The
- * `removeOnFail.count` cap bounds Redis memory growth under failure storms.
+ * `removeOnFail.count` cap bounds Redis memory growth under failure storms. The backoff jitter
+ * spreads each retry over the upper half of its delay, so jobs that failed together (a Redis
+ * outage, a downstream timeout) do not all retry in the same instant.
  */
 declare const DEFAULT_JOB_OPTIONS: {
     readonly attempts: 3;
     readonly backoff: {
         readonly type: "exponential";
         readonly delay: 2000;
+        readonly jitter: 0.5;
     };
     readonly removeOnComplete: {
         readonly age: number;
@@ -1427,7 +1512,7 @@ declare const DEFAULT_JOB_OPTIONS: {
 };
 /** Default TTL (ms) for the metrics cache. */
 declare const DEFAULT_METRICS_CACHE_TTL_MS: 5000;
-/** Default window (ms) for in-flight jobs to drain before force-close on shutdown. */
+/** Default window (ms) for in-flight jobs to drain before the worker is stopped on shutdown. */
 declare const DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS: 30000;
 
 /**

package/dist/server/index.d.ts

@@ -58,7 +58,10 @@ interface BymaxQueueModuleOptions {
     connection: QueueConnectionConfig;
     /** Default options applied to every job enqueued through the service. */
     defaultJobOptions?: JobsOptions;
-    /** Prefix for all Redis keys (multi-tenant isolation). Default: 'bull'. */
+    /**
+     * Prefix for all Redis keys, a namespace and not an access control: anything that can reach the
+     * Redis instance can read every prefix on it. Default: 'bull'.
+     */
     prefix?: string;
     /** Default options applied to every Queue, merged with the job/prefix defaults. */
     queueOptions?: Partial<Omit<QueueOptions, 'connection' | 'defaultJobOptions' | 'prefix'>>;
@@ -87,8 +90,28 @@ interface BymaxQueueModuleOptions {
      * Default: true.
      */
     isGlobal?: boolean;
-    /** Mode B only: milliseconds to wait for Redis `ready` before throwing. Default: 10_000. */
+    /**
+     * Mode B only: the startup budget, in milliseconds, for Redis to reach `ready`. Connection errors
+     * while the client is still reconnecting do not end the wait; the budget does, with
+     * `CONNECTION_TIMEOUT`, and the client the library opened is closed. Default: 10_000.
+     */
     connectionReadyTimeoutMs?: number;
+    /**
+     * Mode B only: the deadline, in milliseconds, for one Redis command on the connection the library
+     * opened (ioredis `commandTimeout`). A command that gets no reply in time rejects instead of
+     * waiting out ioredis' own retry window. An `options.commandTimeout` in the connection config
+     * wins. Worker and QueueEvents connections never inherit it, because they block by design.
+     * Default: 5_000.
+     */
+    commandTimeoutMs?: number;
+    /**
+     * The deadline, in milliseconds, for one `QueueService` call that reaches Redis (`enqueue`,
+     * `getJob`, `getMetrics`, the scheduler, pause and clean calls, and the rest) in either connection
+     * mode, including the wait for the client to be ready on a queue's first call. When it passes, the
+     * call rejects with `CONNECTION_TIMEOUT`; an `enqueue` may still complete in Redis afterwards, so
+     * retry with a stable `jobId` or `deduplication`. Default: 10_000.
+     */
+    enqueueTimeoutMs?: number;
 }
 /** A factory that produces module options, for async configuration. */
 interface BymaxQueueOptionsFactory {
@@ -236,6 +259,10 @@ interface ResolvedQueueOptions {
     telemetry?: Telemetry;
     /** Mode B ready timeout in milliseconds. */
     connectionReadyTimeoutMs: number;
+    /** Mode B per-command deadline in milliseconds. */
+    commandTimeoutMs: number;
+    /** Deadline in milliseconds for one enqueue call. */
+    enqueueTimeoutMs: number;
 }
 
 /**
@@ -362,7 +389,9 @@ declare class ConnectionResolver {
     /**
      * Merge the consumer's options with the owned-connection policy
      * (`lazyConnect: false`, so the client connects eagerly and `init` can wait
-     * for `ready`) and narrow the result to the shape ioredis 6's constructor
+     * for `ready`; a command deadline, so a frozen Redis fails a call in seconds; and no offline
+     * queue, so a call made during an outage fails at once instead of buffering without bound —
+     * each only where the consumer has not chosen a value) and narrow the result to the shape ioredis 6's constructor
      * accepts. The runtime object is unchanged — the cast only drops the
      * `undefined` that `RedisOptions.replyMapping` carries and the constructor
      * rejects.
@@ -374,11 +403,26 @@ declare class ConnectionResolver {
     getMode(): QueueConnectionMode;
     /** Whether the library owns (and must close) the connection. */
     isOwned(): boolean;
+    /**
+     * Settle when the client can take a command. While it is still connecting or reconnecting, every
+     * caller shares one wait on its `ready` event, so a health check that polls through a long outage
+     * adds one listener set to the client, not one per call, and gives it back when Redis returns. A
+     * lazy client (`wait`) connects on its first command and a finished one (`end`) never becomes
+     * ready, so both are left for the call itself.
+     */
+    awaitReady(): Promise<void>;
     /** Close the library-owned connection on shutdown; never touch a BYO client. */
     teardown(): Promise<void>;
     /** Validate and adopt a bring-your-own client for the Queue role. */
     private initModeA;
-    /** Resolve when the owned client reaches `ready`, or reject on timeout/error. */
+    /**
+     * Resolve when the owned client reaches `ready`. A connection error while the client is still
+     * reconnecting does not end the wait — a Redis that restarts during a deploy refuses connections
+     * for a moment first — so the budget does. The two exceptions are an answer from the server that
+     * waiting cannot change (a refused credential) and a client that has stopped reconnecting; both
+     * reject at once. The rejection carries the last error's code and never its message, which can
+     * name the host.
+     */
     private waitReady;
 }
 
@@ -412,13 +456,27 @@ declare class QueueService {
      * @param overrides - Optional per-queue option overrides.
      */
     getOrCreateQueue<TData = unknown, TResult = unknown>(queueName: string, overrides?: Partial<Omit<QueueOptions, 'connection' | 'prefix'>>): Queue<TData, TResult>;
+    /**
+     * Run one Redis call under the per-call deadline (`enqueueTimeoutMs`), reporting every way Redis
+     * can fail to answer as the documented `CONNECTION_TIMEOUT`: the deadline passing, an ioredis
+     * command timeout, or a call refused because the connection is down.
+     *
+     * The first call on a queue name waits for the client to be ready through ONE wait shared by all
+     * callers, instead of letting BullMQ start its own unbounded wait per call, so a caller that
+     * polls through an outage does not pile up listeners. The call runs only if it is still within
+     * its deadline when the client is ready; a caller that was told it timed out never has its call
+     * run later, which would turn its retry into a duplicate.
+     */
+    private call;
+    /** Settle when a call on `queueName` may start: at once for a queue that has been used before. */
+    private afterReady;
     /** Resolve the raw cached queue (default generics) for internal delegation. */
     private queueFor;
     /**
      * Add a single job to a queue. The queue is created lazily if needed.
      *
      * Delivery is **at-least-once** — a handler may run more than once for the same
-     * job (worker crash, lock expiry, or a shutdown force-close). Make handlers
+     * job (worker crash, lock expiry, or a shutdown that outlasts the drain budget). Make handlers
      * idempotent: use an idempotency key on writes, prefer upserts over inserts, or
      * keep an "already-processed" marker keyed by `job.id`.
      *
@@ -492,7 +550,9 @@ declare class QueueService {
      * @param queueName - Target queue.
      * @param status - Status filter.
      * @param start - Starting index (inclusive). Default: 0.
-     * @param end - Ending index (inclusive). Default: 50.
+     * @param end - Ending index (inclusive). Default: 50. The window may span at most
+     *   `MAX_JOBS_PAGE_SIZE` (1000) jobs, and BullMQ's `-1` (everything) is refused.
+     * @throws {QueueException} `INVALID_OPTIONS` when the window is not a bounded range of integers.
      */
     getJobs<TData = unknown, TResult = unknown>(queueName: string, status: JobStatus, start?: number, end?: number): Promise<TypedJob<TData, TResult>[]>;
     /**
@@ -597,6 +657,7 @@ declare class QueueService {
  * })
  */
 declare class FlowService {
+    #private;
     private readonly logger;
     private readonly producer?;
     constructor(connection: ConnectionResolver, enabled: boolean, prefix: string, telemetry?: Telemetry);
@@ -629,6 +690,8 @@ declare class FlowService {
      * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled.
      */
     addBulk(flows: readonly FlowJob[]): Promise<JobNode[]>;
+    /** The command deadline of the producer connection, read when a command has timed out. */
+    private commandTimeout;
     /**
      * Escape hatch returning the underlying `FlowProducer` for advanced use cases.
      * Prefer {@link FlowService.add} / {@link FlowService.addBulk} when possible.
@@ -751,6 +814,14 @@ interface WorkerOptions {
     lockDuration?: number;
     /** Interval between stalled-job checks, in milliseconds. Default: 30_000. */
     stalledInterval?: number;
+    /**
+     * Fail a job whose handler has not settled after this many milliseconds, so it retries under the
+     * job's `attempts` and `backoff` and its concurrency slot is freed. The handler's `signal` aborts
+     * at that moment; a handler that ignores it keeps running in the background. There is no default:
+     * without it a handler that never settles holds its slot indefinitely. Not available for
+     * sandboxed workers. Range: 1 to 2_147_483_647.
+     */
+    jobTimeoutMs?: number;
 }
 
 /**
@@ -773,8 +844,13 @@ interface WorkerOptions {
 interface ProgrammaticWorkerConfig<TData = unknown, TResult = unknown> {
     /** BullMQ queue the worker should consume. */
     queueName: string;
-    /** Async function that processes a single job. Must be idempotent. */
-    handler: (job: Job<TData, TResult>) => Promise<TResult>;
+    /**
+     * Async function that processes a single job. Must be idempotent. Its optional second argument
+     * is the job's `AbortSignal`: it aborts when the job's `jobTimeoutMs` passes or when BullMQ
+     * cancels the job (`worker.cancelJob()`, `worker.cancelAllJobs()`). Closing the worker does not
+     * abort it. Pass it to whatever the handler awaits so the work stops with the job.
+     */
+    handler: (job: Job<TData, TResult>, signal?: AbortSignal) => Promise<TResult>;
     /** Optional worker tuning overrides. */
     options?: WorkerOptions;
 }
@@ -912,6 +988,14 @@ declare class WorkerRegistry {
      * @throws {QueueException} `WORKER_REGISTRATION_FAILED` when values are out of range.
      */
     private validateOptions;
+    /**
+     * Validate `jobTimeoutMs`, which must be a timer delay Node honours: above 2^31 - 1 ms it would
+     * fire after 1 ms and fail every job at once.
+     *
+     * @param opts - The caller-supplied options (may be undefined).
+     * @throws {QueueException} `WORKER_REGISTRATION_FAILED` when the value is out of range.
+     */
+    private validateJobTimeout;
     /**
      * Validate that `processorFile` is a safe, reachable artifact path. Accepts
      * absolute paths with `.js`/`.cjs`/`.mjs` extensions and `file:` URLs. Rejects
@@ -1020,9 +1104,9 @@ declare class QueueEventsRegistry {
  * HTTP server has stopped, it releases what a request can still be using: the
  * flow producer, the cached queues, and finally the Queue-role connection.
  *
- * Delivery is at-least-once: when a worker exceeds the drain budget it is
- * force-closed and its in-flight job becomes `stalled` and is retried by another
- * worker. Handlers must therefore be idempotent, and `lockDuration` should
+ * Delivery is at-least-once: when a worker exceeds the drain budget it is stopped
+ * without waiting for its job, whose lock then expires so the job becomes `stalled`
+ * and is retried by another worker. Handlers must therefore be idempotent, and `lockDuration` should
  * comfortably exceed the worst-case handler runtime so healthy long jobs are
  * never treated as stalled.
  * @layer server/lifecycle
@@ -1071,28 +1155,26 @@ declare class QueueLifecycle implements OnModuleDestroy, OnApplicationShutdown {
      */
     onApplicationShutdown(): Promise<void>;
     /**
-     * Close every worker with a bounded drain, force-closing any that exceed the
-     * budget. Returns the number of workers that had to be force-closed.
+     * Stop every worker in parallel, each bounded by what is left of the shutdown budget. A worker
+     * is paused first (it stops fetching and waits for its active jobs) and then closed. One that is
+     * still busy when the budget ends is closed with `close(true)`: because `pause` does not start a
+     * close, that is the worker's FIRST close, so it does not wait for the job and stops the lock
+     * renewal that would otherwise keep running and keep the process alive. The job's lock then
+     * expires, and it stalls and is retried elsewhere. Returns how many workers were stopped
+     * without draining.
      *
-     * @returns The count of force-closed workers.
+     * @param deadline - The epoch millisecond at which the shutdown budget ends.
+     * @returns The count of workers stopped without draining.
      */
     private closeWorkers;
-    /**
-     * Race a graceful `worker.close()` against a timer. `worker.close()` already
-     * drains active jobs and takes no timeout argument, so the timer is the only
-     * way to bound the wait. Rejects with a timeout error when the budget elapses.
-     *
-     * @param worker - The worker to close.
-     * @param timeoutMs - The drain budget in milliseconds.
-     */
-    private closeWorkerWithTimeout;
-    /** Close every cached `QueueEvents`, swallowing individual failures. */
+    /** Close every cached `QueueEvents` in parallel within the budget, swallowing failures. */
     private closeQueueEvents;
     /**
-     * Close the duplicated worker/queue-events connections the library opened.
-     * BullMQ treats a passed-in client as shared and never closes it, so the
-     * library must release these explicitly. In Mode A the consumer's shared
-     * client is never among them.
+     * Close the duplicated worker/queue-events connections the library opened, in parallel. BullMQ
+     * treats a passed-in client as shared and never closes it, so the library must release these
+     * explicitly. A connection that does not quit within the budget is disconnected, which also
+     * releases anything still blocked on it. In Mode A the consumer's shared client is never among
+     * them.
      */
     private closeDuplicatedConnections;
     /**
@@ -1161,7 +1243,7 @@ declare function Processor(queueName: string, options?: WorkerOptions): ClassDec
  * an entry to the accumulated metadata array.
  *
  * Delivery is at-least-once: a handler may run more than once for the same job
- * (worker crash, lock expiry, or a shutdown force-close). Handlers MUST be
+ * (worker crash, lock expiry, or a shutdown that outlasts the drain budget). Handlers MUST be
  * idempotent — use an idempotency key on writes, prefer upserts over inserts, or
  * keep an "already-processed" marker keyed by `job.id`.
  *
@@ -1213,7 +1295,7 @@ type WorkerEventName = 'completed' | 'failed' | 'progress' | 'active' | 'stalled
  * overwriting each other.
  *
  * Delivery is at-least-once. A `'stalled'` job — for example after a shutdown
- * force-close or a lock expiry — is re-run by another worker: this is the
+ * that outlasts the drain budget, or a lock expiry — is re-run by another worker: this is the
  * visible at-least-once path, so handlers must be idempotent. Set `lockDuration`
  * comfortably above the worst-case handler runtime to avoid false stalls.
  *
@@ -1408,13 +1490,16 @@ declare const DEFAULT_WORKER_CONCURRENCY: 2;
 declare const MAX_WORKER_CONCURRENCY: 1000;
 /**
  * Default options applied to every job enqueued through the service. The
- * `removeOnFail.count` cap bounds Redis memory growth under failure storms.
+ * `removeOnFail.count` cap bounds Redis memory growth under failure storms. The backoff jitter
+ * spreads each retry over the upper half of its delay, so jobs that failed together (a Redis
+ * outage, a downstream timeout) do not all retry in the same instant.
  */
 declare const DEFAULT_JOB_OPTIONS: {
     readonly attempts: 3;
     readonly backoff: {
         readonly type: "exponential";
         readonly delay: 2000;
+        readonly jitter: 0.5;
     };
     readonly removeOnComplete: {
         readonly age: number;
@@ -1427,7 +1512,7 @@ declare const DEFAULT_JOB_OPTIONS: {
 };
 /** Default TTL (ms) for the metrics cache. */
 declare const DEFAULT_METRICS_CACHE_TTL_MS: 5000;
-/** Default window (ms) for in-flight jobs to drain before force-close on shutdown. */
+/** Default window (ms) for in-flight jobs to drain before the worker is stopped on shutdown. */
 declare const DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS: 30000;
 
 /**