@bymax-one/nest-queue 1.2.14 → 1.2.16

package/dist/server/index.d.cts

@@ -105,9 +105,11 @@ interface BymaxQueueModuleOptions {
      */
     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.
+     * 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;
 }
@@ -401,6 +403,14 @@ 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. */
@@ -446,20 +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>;
-    /** 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.
+     * 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`.
      *
@@ -580,9 +597,11 @@ declare class QueueService {
      *
      * @param queueName - Target queue.
      * @param start - Page start index (inclusive). Default: 0.
-     * @param end - Page end index (inclusive). Default: 50.
+     * @param end - Page end index (inclusive). Default: 50. The window may span at most
+     *   `MAX_JOBS_PAGE_SIZE` (1000) entries, and BullMQ's `-1` (everything) is refused.
      * @param asc - Sort ascending by next run time. Default: true.
      * @returns The registered schedulers in the requested page.
+     * @throws {QueueException} `INVALID_OPTIONS` when the window is not a bounded range of integers.
      */
     getJobSchedulers(queueName: string, start?: number, end?: number, asc?: boolean): Promise<Awaited<ReturnType<Queue['getJobSchedulers']>>>;
     /** Pause a queue, halting the processing of new jobs. */
@@ -643,7 +662,7 @@ declare class FlowService {
     #private;
     private readonly logger;
     private readonly producer?;
-    constructor(connection: ConnectionResolver, enabled: boolean, prefix: string, telemetry?: Telemetry);
+    constructor(connection: ConnectionResolver, enabled: boolean, prefix: string, telemetry?: Telemetry, enqueueTimeoutMs?: number);
     /**
      * Add a flow tree (a parent with its descendant children). The root job
      * becomes processable only after every descendant has completed.
@@ -661,7 +680,8 @@ declare class FlowService {
      *   A job whose custom `jobId` already exists is not added again: its node carries the EXISTING
      *   id with the data of this call, so the tree does not describe what is stored; call
      *   `QueueService.getJob` when you need it.
-     * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled.
+     * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled; `CONNECTION_TIMEOUT`
+     *   when Redis does not answer within `enqueueTimeoutMs` (the flow may still have been added).
      */
     add(flow: FlowJob): Promise<JobNode>;
     /**
@@ -670,9 +690,17 @@ declare class FlowService {
      * @param flows - Flow tree definitions.
      * @returns The root `JobNode` for each flow, in input order.
      *   A job whose custom `jobId` already exists is not added again; see {@link FlowService.add}.
-     * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled.
+     * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled;
+     *   `BULK_ENQUEUE_FAILED` for more than 1000 flows; `CONNECTION_TIMEOUT` as for
+     *   {@link FlowService.add}.
      */
     addBulk(flows: readonly FlowJob[]): Promise<JobNode[]>;
+    /**
+     * Hold the caller to `enqueueTimeoutMs`, and report a command timeout or a down connection as
+     * `CONNECTION_TIMEOUT`. A call that timed out may still have been added: BullMQ is not asked to
+     * cancel it.
+     */
+    private bounded;
     /** The command deadline of the producer connection, read when a command has timed out. */
     private commandTimeout;
     /**
@@ -964,8 +992,9 @@ declare class WorkerRegistry {
     private guardDuplicate;
     /**
      * Validate tunable options before constructing a Worker.
-     * Enforces `concurrency` in `[1, MAX_WORKER_CONCURRENCY]` and
-     * `limiter.max`/`limiter.duration` `>= 1`.
+     * Enforces whole-number `concurrency` in `[1, MAX_WORKER_CONCURRENCY]`, whole-number
+     * `limiter.max`/`limiter.duration` `>= 1`, and `lockDuration`/`stalledInterval` within
+     * 1000..2^31 - 1.
      *
      * @param opts - The caller-supplied options (may be undefined).
      * @throws {QueueException} `WORKER_REGISTRATION_FAILED` when values are out of range.
@@ -1087,9 +1116,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
@@ -1138,11 +1167,16 @@ declare class QueueLifecycle implements OnModuleDestroy, OnApplicationShutdown {
      */
     onApplicationShutdown(): Promise<void>;
     /**
-     * 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.
+     * 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.
      *
      * @param deadline - The epoch millisecond at which the shutdown budget ends.
-     * @returns The count of force-closed workers.
+     * @returns The count of workers stopped without draining.
      */
     private closeWorkers;
     /** Close every cached `QueueEvents` in parallel within the budget, swallowing failures. */
@@ -1221,7 +1255,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`.
  *
@@ -1273,7 +1307,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.
  *
@@ -1490,7 +1524,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

@@ -105,9 +105,11 @@ interface BymaxQueueModuleOptions {
      */
     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.
+     * 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;
 }
@@ -401,6 +403,14 @@ 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. */
@@ -446,20 +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>;
-    /** 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.
+     * 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`.
      *
@@ -580,9 +597,11 @@ declare class QueueService {
      *
      * @param queueName - Target queue.
      * @param start - Page start index (inclusive). Default: 0.
-     * @param end - Page end index (inclusive). Default: 50.
+     * @param end - Page end index (inclusive). Default: 50. The window may span at most
+     *   `MAX_JOBS_PAGE_SIZE` (1000) entries, and BullMQ's `-1` (everything) is refused.
      * @param asc - Sort ascending by next run time. Default: true.
      * @returns The registered schedulers in the requested page.
+     * @throws {QueueException} `INVALID_OPTIONS` when the window is not a bounded range of integers.
      */
     getJobSchedulers(queueName: string, start?: number, end?: number, asc?: boolean): Promise<Awaited<ReturnType<Queue['getJobSchedulers']>>>;
     /** Pause a queue, halting the processing of new jobs. */
@@ -643,7 +662,7 @@ declare class FlowService {
     #private;
     private readonly logger;
     private readonly producer?;
-    constructor(connection: ConnectionResolver, enabled: boolean, prefix: string, telemetry?: Telemetry);
+    constructor(connection: ConnectionResolver, enabled: boolean, prefix: string, telemetry?: Telemetry, enqueueTimeoutMs?: number);
     /**
      * Add a flow tree (a parent with its descendant children). The root job
      * becomes processable only after every descendant has completed.
@@ -661,7 +680,8 @@ declare class FlowService {
      *   A job whose custom `jobId` already exists is not added again: its node carries the EXISTING
      *   id with the data of this call, so the tree does not describe what is stored; call
      *   `QueueService.getJob` when you need it.
-     * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled.
+     * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled; `CONNECTION_TIMEOUT`
+     *   when Redis does not answer within `enqueueTimeoutMs` (the flow may still have been added).
      */
     add(flow: FlowJob): Promise<JobNode>;
     /**
@@ -670,9 +690,17 @@ declare class FlowService {
      * @param flows - Flow tree definitions.
      * @returns The root `JobNode` for each flow, in input order.
      *   A job whose custom `jobId` already exists is not added again; see {@link FlowService.add}.
-     * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled.
+     * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled;
+     *   `BULK_ENQUEUE_FAILED` for more than 1000 flows; `CONNECTION_TIMEOUT` as for
+     *   {@link FlowService.add}.
      */
     addBulk(flows: readonly FlowJob[]): Promise<JobNode[]>;
+    /**
+     * Hold the caller to `enqueueTimeoutMs`, and report a command timeout or a down connection as
+     * `CONNECTION_TIMEOUT`. A call that timed out may still have been added: BullMQ is not asked to
+     * cancel it.
+     */
+    private bounded;
     /** The command deadline of the producer connection, read when a command has timed out. */
     private commandTimeout;
     /**
@@ -964,8 +992,9 @@ declare class WorkerRegistry {
     private guardDuplicate;
     /**
      * Validate tunable options before constructing a Worker.
-     * Enforces `concurrency` in `[1, MAX_WORKER_CONCURRENCY]` and
-     * `limiter.max`/`limiter.duration` `>= 1`.
+     * Enforces whole-number `concurrency` in `[1, MAX_WORKER_CONCURRENCY]`, whole-number
+     * `limiter.max`/`limiter.duration` `>= 1`, and `lockDuration`/`stalledInterval` within
+     * 1000..2^31 - 1.
      *
      * @param opts - The caller-supplied options (may be undefined).
      * @throws {QueueException} `WORKER_REGISTRATION_FAILED` when values are out of range.
@@ -1087,9 +1116,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
@@ -1138,11 +1167,16 @@ declare class QueueLifecycle implements OnModuleDestroy, OnApplicationShutdown {
      */
     onApplicationShutdown(): Promise<void>;
     /**
-     * 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.
+     * 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.
      *
      * @param deadline - The epoch millisecond at which the shutdown budget ends.
-     * @returns The count of force-closed workers.
+     * @returns The count of workers stopped without draining.
      */
     private closeWorkers;
     /** Close every cached `QueueEvents` in parallel within the budget, swallowing failures. */
@@ -1221,7 +1255,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`.
  *
@@ -1273,7 +1307,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.
  *
@@ -1490,7 +1524,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;
 
 /**