@bymax-one/nest-queue 1.2.13 → 1.2.14

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,26 @@ 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 `enqueue` or `enqueueBulk` call in either connection mode.
+     * When it passes, the call rejects with `CONNECTION_TIMEOUT`; the add 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 +257,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 +387,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.
@@ -378,7 +405,14 @@ declare class ConnectionResolver {
     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,6 +446,13 @@ 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>;
+    /** The error a producer call receives when Redis does not answer within `enqueueTimeoutMs`. */
+    private enqueueTimeout;
+    /**
+     * Await a Redis call, reporting an ioredis command timeout as `CONNECTION_TIMEOUT` with the
+     * operation and the command deadline of the connection in force.
+     */
+    private call;
     /** Resolve the raw cached queue (default generics) for internal delegation. */
     private queueFor;
     /**
@@ -492,7 +533,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 +640,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 +673,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 +797,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 +827,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 +971,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
@@ -1071,28 +1138,21 @@ 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.
+     * Close every worker in parallel, each bounded by what is left of the shutdown budget, and
+     * force-close any that exceed it. Returns the number of workers that had to be force-closed.
      *
+     * @param deadline - The epoch millisecond at which the shutdown budget ends.
      * @returns The count of force-closed workers.
      */
     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;
     /**
@@ -1408,13 +1468,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;

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,26 @@ 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 `enqueue` or `enqueueBulk` call in either connection mode.
+     * When it passes, the call rejects with `CONNECTION_TIMEOUT`; the add 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 +257,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 +387,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.
@@ -378,7 +405,14 @@ declare class ConnectionResolver {
     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,6 +446,13 @@ 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>;
+    /** The error a producer call receives when Redis does not answer within `enqueueTimeoutMs`. */
+    private enqueueTimeout;
+    /**
+     * Await a Redis call, reporting an ioredis command timeout as `CONNECTION_TIMEOUT` with the
+     * operation and the command deadline of the connection in force.
+     */
+    private call;
     /** Resolve the raw cached queue (default generics) for internal delegation. */
     private queueFor;
     /**
@@ -492,7 +533,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 +640,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 +673,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 +797,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 +827,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 +971,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
@@ -1071,28 +1138,21 @@ 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.
+     * Close every worker in parallel, each bounded by what is left of the shutdown budget, and
+     * force-close any that exceed it. Returns the number of workers that had to be force-closed.
      *
+     * @param deadline - The epoch millisecond at which the shutdown budget ends.
      * @returns The count of force-closed workers.
      */
     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;
     /**
@@ -1408,13 +1468,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;