@bymax-one/nest-queue 1.2.14 → 1.2.15

package/CHANGELOG.md

@@ -11,6 +11,29 @@ versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.2.15] — 2026-11-14
+
+Against 1.2.14 the built declarations gain `ConnectionResolver.awaitReady()`; nothing else in the public API changes.
+
+### Fixed
+
+- **A call made while the connection is down now reports the documented error.** With the owned connection's offline queue off, a call on a queue already in use during a refused-connection outage rejected at once with ioredis's plain `Stream isn't writeable and enableOfflineQueue options is false`, so a host retrying on `CONNECTION_TIMEOUT` as documented never retried. It is now `CONNECTION_TIMEOUT` with `details.operation` and `details.reason: 'offline'`, and the ioredis error as `cause`.
+- **The first call on a queue no longer waits for Redis without a deadline.** `getMetrics`, `getJob`, `getJobs`, the scheduler calls, `pauseQueue`, `resumeQueue` and `cleanQueue` on a queue name not yet used waited in BullMQ for the client to be ready, with no bound, for as long as the outage lasted. Every `QueueService` call is now bounded by `enqueueTimeoutMs` and rejects with `CONNECTION_TIMEOUT`.
+- **Shutdown no longer leaves a worker running after its drain budget.** A handler that never settled kept the worker's lock-renewal timer alive after `app.close()`: the process did not exit by itself and logged `Connection is closed.` repeatedly. BullMQ ignores a forced close once a graceful one has started, so the worker is now paused first and closed with `close(true)` as its first close when the budget runs out. What the abandoned handler produces after the budget, a result or a failure, is dropped, so BullMQ cannot resume the stopped worker and reopen its connection. The handler's own promise still keeps running, since user code cannot be cancelled. A sandboxed worker is the exception: its job runs in a child process the registry cannot wrap, and in a measured run the host process did not exit by itself after the budget ended with such a job still running.
+
+### Documentation
+
+- `enqueueTimeoutMs` is documented as the per-call deadline of every `QueueService` call, and `queue.connection_timeout` as covering a connection that is down.
+
+#### Apply to a derived backend
+
+- If you match the ioredis error `Stream isn't writeable and enableOfflineQueue options is false` on a call, match `CONNECTION_TIMEOUT` instead; `details.reason` is `'offline'` and the original error is its `cause`.
+- If a `getMetrics`, `getJob`, `getJobs`, scheduler, pause, resume or clean call relied on waiting out an outage on a queue's first use, it now rejects with `CONNECTION_TIMEOUT` after `enqueueTimeoutMs`; raise the option to wait longer.
+- If you replace `ConnectionResolver` with your own implementation, add `awaitReady(): Promise<void>`: `QueueService` calls it before the first call on each queue name.
+- If you parse the shutdown log lines, the wording changed: `forcing close` is gone and the summary reads `N worker(s) stopped without draining`.
+
+---
+
 ## [1.2.14] — 2026-11-14
 
 Several defaults change in this release, so read the Apply note below. A boot that succeeds, an
@@ -1013,7 +1036,8 @@ v6 peer range.
 
 ---
 
-[Unreleased]: https://github.com/bymaxone/nest-queue/compare/v1.2.14...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-queue/compare/v1.2.15...HEAD
+[1.2.15]: https://github.com/bymaxone/nest-queue/compare/v1.2.14...v1.2.15
 [1.2.14]: https://github.com/bymaxone/nest-queue/compare/v1.2.13...v1.2.14
 [1.2.13]: https://github.com/bymaxone/nest-queue/compare/v1.2.12...v1.2.13
 [1.2.12]: https://github.com/bymaxone/nest-queue/compare/v1.2.11...v1.2.12

package/README.md

@@ -66,7 +66,7 @@ peer dependencies, so you control exact versions and the supply-chain surface st
 - ✅ **Dual-mode connection** — bring your own `ioredis` client, or let the library open its own from a URL or an options object
 - ✅ **Per-role retry policy** — `maxRetriesPerRequest: null` reaches only the duplicated Worker and QueueEvents connections; the producer keeps a finite retry limit, a 5 s command deadline and no offline queue on the connection the library opens, and `enqueue` has its own 10 s deadline, so a Redis outage rejects a call in seconds instead of holding the request; a shared client with `maxRetriesPerRequest: null` is the exception, and the library warns about it at boot
 - ✅ **One namespace, four objects** — the configured `prefix` reaches `Queue`, `Worker`, `QueueEvents` **and** `FlowProducer`, so producers and consumers can never end up on separate keyspaces
-- ✅ **Bounded graceful shutdown** — a single ordered sequence drains every worker under a deadline and then force-closes; delivery is at-least-once by design, so handlers must be idempotent
+- ✅ **Bounded graceful shutdown** — a single ordered sequence drains every worker under one deadline and then stops any that are still busy, whose jobs stall and are retried; delivery is at-least-once by design, so handlers must be idempotent
 - ✅ **No unlistened emitter** — every `Queue`, `Worker`, `QueueEvents` and `FlowProducer` the library creates carries a fallback `error` listener, so a transient Redis fault cannot become an uncaught exception in your process; your own `@OnWorkerEvent('error')` or `@OnQueueEvent('error')` still runs alongside it
 
 ### 🧩 Developer Experience
@@ -243,7 +243,7 @@ Every option passed to `forRoot` / `forRootAsync`. Only `connection` is required
 | `shutdown.drainOnShutdown` | `boolean`                                        | `false`                                                                                                                                                    | Development and test only: once the HTTP server has stopped, call `drain()` on every cached queue, which **removes** its waiting jobs (delayed and active jobs are left alone). Leave it `false` in production.                                                                                                                            |
 | `connectionReadyTimeoutMs` | `number`                                         | `10_000`                                                                                                                                                   | Mode B only: the budget for Redis to reach `ready`. A connection error while the client is still reconnecting does not end the wait; when the budget ends, startup fails with `CONNECTION_TIMEOUT` carrying `lastErrorCode` (a code such as `ECONNREFUSED`, never the message) and the client the library opened is closed.                |
 | `commandTimeoutMs`         | `number`                                         | `5_000`                                                                                                                                                    | Mode B only: the deadline for one Redis command on the connection the library opened (ioredis `commandTimeout`); an `options.commandTimeout` wins. A call that hits it rejects with `CONNECTION_TIMEOUT` (`details` carries `operation` and `timeoutMs`), as when `enqueueTimeoutMs` passes. Worker and QueueEvents connections have none. |
-| `enqueueTimeoutMs`         | `number`                                         | `10_000`                                                                                                                                                   | The deadline for one `enqueue` or `enqueueBulk`, in either mode; it rejects with `CONNECTION_TIMEOUT`, and the add may still complete in Redis, so retry with a stable `jobId` or `deduplication`.                                                                                                                                         |
+| `enqueueTimeoutMs`         | `number`                                         | `10_000`                                                                                                                                                   | The deadline for one `QueueService` call that reaches Redis, in either mode, including the wait for the client to be ready on a queue's first call; it rejects with `CONNECTION_TIMEOUT`, and an `enqueue` may still complete in Redis, so retry with a stable `jobId` or `deduplication`.                                                 |
 | `isGlobal`                 | `boolean`                                        | `true`                                                                                                                                                     | Register the module globally, so `QueueService` is injectable without re-importing.                                                                                                                                                                                                                                                        |
 
 > [!WARNING]
@@ -440,7 +440,7 @@ When a custom `jobId` already exists, or a `deduplication` rule keeps the job th
 
 ### A timed-out `enqueue` may still have been added
 
-When Redis does not answer in time, whether within `commandTimeoutMs` on the connection the library opened or within `enqueueTimeoutMs`, `enqueue` and `enqueueBulk` reject with `CONNECTION_TIMEOUT`, but the library cannot cancel the command: if Redis applies it late, the job exists anyway. Retrying a call that timed out can therefore add the job twice. For anything that must not run twice, pass a deterministic `jobId` (for example one derived from the business key): BullMQ ignores a second add with the same `jobId` for as long as the first job is still stored, so a retry inside that window is safe. A completed job is removed by `removeOnComplete`, and from then on the same `jobId` adds a new job, so keep the retry inside that window or keep the handler idempotent. A `deduplication` rule gives the same guarantee for work that is allowed to repeat after a window.
+When Redis does not answer in time, whether within `commandTimeoutMs` on the connection the library opened or within `enqueueTimeoutMs`, or the connection is down, `enqueue` and `enqueueBulk` reject with `CONNECTION_TIMEOUT`, but the library cannot cancel the command: if Redis applies it late, the job exists anyway. Retrying a call that timed out can therefore add the job twice. For anything that must not run twice, pass a deterministic `jobId` (for example one derived from the business key): BullMQ ignores a second add with the same `jobId` for as long as the first job is still stored, so a retry inside that window is safe. A completed job is removed by `removeOnComplete`, and from then on the same `jobId` adds a new job, so keep the retry inside that window or keep the handler idempotent. A `deduplication` rule gives the same guarantee for work that is allowed to repeat after a window.
 
 ### OpenTelemetry
 
@@ -465,10 +465,15 @@ It implements a **bounded drain protocol** with at-least-once semantics:
 1. All workers are closed **in parallel**, within one budget (`drainTimeoutMs`, default 30 s) that
    covers steps 1 to 4 together: however many workers are stuck, consumption stops after one budget,
    not one per worker.
-2. A worker resolves either when it drains normally or when the budget runs out — whichever comes
-   first.
-3. On timeout, the worker is force-closed (`worker.close(true)`), preserving stalled
-   jobs for reprocessing by the next instance.
+2. Each worker is paused (it stops fetching and waits for its active jobs) and then closed, or the
+   budget runs out — whichever comes first.
+3. On timeout, the worker is stopped with `worker.close(true)` as its first close, so it does not
+   wait for the job and its lock renewal ends; the lock expires and the job stalls and is retried
+   by the next instance. What the abandoned handler produces afterwards, a result or a failure, is
+   dropped, so the stopped worker cannot restart its connection. The handler's own promise keeps
+   running, because user code cannot be cancelled. A sandboxed (file-based) worker is the
+   exception: its job runs in a child process the registry cannot wrap, and in a measured run the
+   host process did not exit by itself after the budget ended with such a job still running.
 4. Queue-events and the connections the library opened for workers and queue-events are closed,
    each within what is left of the budget; a connection that has not quit by then is disconnected.
 5. Once NestJS has stopped the HTTP server (`onApplicationShutdown`), the flow producer, the
@@ -478,7 +483,7 @@ It implements a **bounded drain protocol** with at-least-once semantics:
 
 **Handlers must be idempotent.** Use `jobId`, `deduplication`, or application-level
 idempotency keys to guard against reprocessing a job that was partially handled before
-a crash or force-close.
+a crash or a shutdown that outlasts the drain budget.
 
 **DLQ pattern.** When a job exhausts its `attempts`, move it to a dead-letter queue:
 
@@ -506,14 +511,14 @@ BymaxQueueModule.forRoot({
 
 ## 🤔 Why over `@nestjs/bullmq`
 
-| Concern       | `@nestjs/bullmq` (official)                          | `@bymax-one/nest-queue`                                                          |
-| ------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------- |
-| Module setup  | `BullModule.forRoot()` + `registerQueue()` per queue | Single `forRoot`/`forRootAsync`; queues created on demand by name                |
-| Connection    | Manual ioredis + `maxRetriesPerRequest` wiring       | Dual mode (BYO / lib-owned); correct per-role retry policy applied automatically |
-| Job defaults  | Per `registerQueue`                                  | Centralized opinionated defaults with per-queue/per-job overrides                |
-| Producer API  | `@InjectQueue` + raw `queue.add`                     | Typed `enqueue<TData, TResult>()`, `enqueueBulk`, `upsertJobScheduler`           |
-| Shutdown      | Framework closes workers                             | Explicit bounded-drain protocol; force-close + stalled accounting                |
-| Observability | Manual                                               | `telemetry` passthrough (OpenTelemetry) + `MetricsService`                       |
+| Concern       | `@nestjs/bullmq` (official)                          | `@bymax-one/nest-queue`                                                                  |
+| ------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Module setup  | `BullModule.forRoot()` + `registerQueue()` per queue | Single `forRoot`/`forRootAsync`; queues created on demand by name                        |
+| Connection    | Manual ioredis + `maxRetriesPerRequest` wiring       | Dual mode (BYO / lib-owned); correct per-role retry policy applied automatically         |
+| Job defaults  | Per `registerQueue`                                  | Centralized opinionated defaults with per-queue/per-job overrides                        |
+| Producer API  | `@InjectQueue` + raw `queue.add`                     | Typed `enqueue<TData, TResult>()`, `enqueueBulk`, `upsertJobScheduler`                   |
+| Shutdown      | Framework closes workers                             | Explicit bounded-drain protocol; stops a busy worker at the deadline; stalled accounting |
+| Observability | Manual                                               | `telemetry` passthrough (OpenTelemetry) + `MetricsService`                               |
 
 **Choose this library** when you want a single opinionated setup, the `@bymax-one/nest-cache`
 connection-sharing story, enforced defaults, and a tested bounded-shutdown protocol.
@@ -552,7 +557,7 @@ wire connection and defaults yourself.
                         (@Processor / @Process / @OnWorkerEvent)
                                         │
                                  QueueLifecycle
-                     (bounded drain → force close → disconnect)
+                     (bounded drain → stop → disconnect)
 ```
 
 ### Design Principles
@@ -850,18 +855,18 @@ try {
 }
 ```
 
-| Code                                     | HTTP | When thrown                                                                                                                                                                                                                                                                                                                                                                             |
-| ---------------------------------------- | :--: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `queue.invalid_options`                  | 500  | Module options failed bootstrap validation — missing `connection`, mutually exclusive connection arms, non-positive `shutdown.drainTimeoutMs`, or negative `metrics.cacheTtlMs`                                                                                                                                                                                                         |
-| `queue.connection_invalid`               | 500  | The resolver has no usable client: not yet initialized, Mode A's injected client is in an unusable `status`, or a Mode B client was refused by the server (`WRONGPASS`, `NOAUTH`) or stopped reconnecting during startup                                                                                                                                                                |
-| `queue.connection_requires_null_retries` | 500  | A consumer connection could not be coerced to `maxRetriesPerRequest: null`                                                                                                                                                                                                                                                                                                              |
-| `queue.connection_timeout`               | 500  | Mode B: Redis did not reach `ready` within `connectionReadyTimeoutMs` (`details` carries `timeoutMs` and the last error's `lastErrorCode`), or a `QueueService`/`FlowService` call got no answer within the connection's `commandTimeoutMs`, or `enqueue`/`enqueueBulk` within `enqueueTimeoutMs` (`details` carries `operation` and `timeoutMs`; an enqueue may still have been added) |
-| `queue.invalid_repeat_options`           | 400  | A Job Scheduler schedule was rejected — invalid cron pattern, or neither `pattern` nor `every`                                                                                                                                                                                                                                                                                          |
-| `queue.duplicate_processor`              | 500  | Two `@Processor` classes claim the same queue name                                                                                                                                                                                                                                                                                                                                      |
-| `queue.flow_disabled`                    | 503  | `FlowService` used without `flows.enabled`                                                                                                                                                                                                                                                                                                                                              |
-| `queue.metrics_disabled`                 | 503  | `MetricsService` used without `metrics.enabled`                                                                                                                                                                                                                                                                                                                                         |
-| `queue.bulk_enqueue_failed`              | 500  | `enqueueBulk` exceeded the 1 000-job cap, or the underlying `addBulk` failed                                                                                                                                                                                                                                                                                                            |
-| `queue.worker_registration_failed`       | 500  | A worker could not be constructed, started, or closed                                                                                                                                                                                                                                                                                                                                   |
+| Code                                     | HTTP | When thrown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ---------------------------------------- | :--: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `queue.invalid_options`                  | 500  | Module options failed bootstrap validation — missing `connection`, mutually exclusive connection arms, non-positive `shutdown.drainTimeoutMs`, or negative `metrics.cacheTtlMs`                                                                                                                                                                                                                                                                                                                |
+| `queue.connection_invalid`               | 500  | The resolver has no usable client: not yet initialized, Mode A's injected client is in an unusable `status`, or a Mode B client was refused by the server (`WRONGPASS`, `NOAUTH`) or stopped reconnecting during startup                                                                                                                                                                                                                                                                       |
+| `queue.connection_requires_null_retries` | 500  | A consumer connection could not be coerced to `maxRetriesPerRequest: null`                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `queue.connection_timeout`               | 500  | Mode B: Redis did not reach `ready` within `connectionReadyTimeoutMs` (`details` carries `timeoutMs` and the last error's `lastErrorCode`), or a `QueueService`/`FlowService` call got no answer from Redis: it timed out (`commandTimeoutMs` on the owned connection, or `enqueueTimeoutMs` for a `QueueService` call; `details` carries `operation` and `timeoutMs`) or the connection is down (`details` carries `operation` and `reason: 'offline'`); an enqueue may still have been added |
+| `queue.invalid_repeat_options`           | 400  | A Job Scheduler schedule was rejected — invalid cron pattern, or neither `pattern` nor `every`                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `queue.duplicate_processor`              | 500  | Two `@Processor` classes claim the same queue name                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `queue.flow_disabled`                    | 503  | `FlowService` used without `flows.enabled`                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `queue.metrics_disabled`                 | 503  | `MetricsService` used without `metrics.enabled`                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `queue.bulk_enqueue_failed`              | 500  | `enqueueBulk` exceeded the 1 000-job cap, or the underlying `addBulk` failed                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `queue.worker_registration_failed`       | 500  | A worker could not be constructed, started, or closed                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 
 ### Reserved codes
 
@@ -869,12 +874,12 @@ These are part of the published catalog and stable, but nothing currently throws
 They are listed so a consumer writing an exhaustive `switch` over `QueueErrorCode`
 compiles today and keeps compiling when a future release starts emitting them.
 
-| Code                              | Why it is not thrown today                                            |
-| --------------------------------- | --------------------------------------------------------------------- |
-| `queue.queue_not_found`           | Queues are created on demand by name, so a lookup never misses        |
-| `queue.job_not_found`             | `getJob` resolves to `null` rather than throwing                      |
-| `queue.invalid_job_data`          | Payloads are opaque; the library does not validate them               |
-| `queue.shutdown_timeout_exceeded` | Exceeding the drain deadline force-closes workers rather than raising |
+| Code                              | Why it is not thrown today                                                    |
+| --------------------------------- | ----------------------------------------------------------------------------- |
+| `queue.queue_not_found`           | Queues are created on demand by name, so a lookup never misses                |
+| `queue.job_not_found`             | `getJob` resolves to `null` rather than throwing                              |
+| `queue.invalid_job_data`          | Payloads are opaque; the library does not validate them                       |
+| `queue.shutdown_timeout_exceeded` | Exceeding the drain deadline stops the workers still busy rather than raising |
 
 The same catalog is exported from `@bymax-one/nest-queue/shared` with no dependencies,
 so a frontend can map codes to messages without importing the server surface.
@@ -908,7 +913,7 @@ If you see it, the client you passed is not a plain ioredis client (a wrapper or
 double whose `duplicate()` ignores its options). Pass the ioredis client itself, or let the
 library open its own connection with Mode B. The producer keeps the client's own retry
 policy; with a finite `maxRetriesPerRequest` that is what lets it fail fast during an outage, and
-`enqueue` is bounded by `enqueueTimeoutMs` whatever the client does.
+every `QueueService` call is bounded by `enqueueTimeoutMs` whatever the client does.
 
 ### A handler never settles (the queue stops moving)
 

package/dist/server/index.cjs

@@ -250,13 +250,14 @@ function duplicateConnection(client) {
 }
 
 // src/server/services/connection-resolver.service.ts
-var _logger, _client, _options;
+var _logger, _client, _options, _pendingReady;
 exports.ConnectionResolver = class ConnectionResolver {
   constructor(options) {
     __privateAdd(this, _logger, new common.Logger(exports.ConnectionResolver.name));
     __privateAdd(this, _client);
     __privateAdd(this, _options);
     __publicField(this, "mode");
+    __privateAdd(this, _pendingReady);
     __privateSet(this, _options, options);
   }
   async init() {
@@ -312,6 +313,17 @@ exports.ConnectionResolver = class ConnectionResolver {
   isOwned() {
     return this.mode === "mode-b-owned";
   }
+  awaitReady() {
+    const client = this.getClient();
+    if (!WAITING_STATUSES.has(client.status)) return Promise.resolve();
+    __privateGet(this, _pendingReady) ?? __privateSet(this, _pendingReady, new Promise((resolve) => {
+      client.once("ready", () => {
+        __privateSet(this, _pendingReady, void 0);
+        resolve();
+      });
+    }));
+    return __privateGet(this, _pendingReady);
+  }
   async teardown() {
     if (this.isOwned() && __privateGet(this, _client)) {
       const client = __privateGet(this, _client);
@@ -332,7 +344,7 @@ exports.ConnectionResolver = class ConnectionResolver {
     }
     if (client.options.maxRetriesPerRequest === null) {
       __privateGet(this, _logger).warn(
-        "The shared client has maxRetriesPerRequest: null, so a producer call made while Redis is unreachable waits for as long as the outage lasts; enqueue is bounded by enqueueTimeoutMs, other QueueService calls are not. Give the client a finite limit to fail fast."
+        "The shared client has maxRetriesPerRequest: null, so a command issued while Redis is unreachable stays queued in the client for as long as the outage lasts. QueueService calls are bounded by enqueueTimeoutMs and the caller is released, but the command is not cancelled. Give the client a finite limit to fail fast."
       );
     }
     const probe = duplicateConnection(client);
@@ -382,10 +394,17 @@ exports.ConnectionResolver = class ConnectionResolver {
 _logger = new WeakMap();
 _client = new WeakMap();
 _options = new WeakMap();
+_pendingReady = new WeakMap();
 exports.ConnectionResolver = __decorateClass([
   common.Injectable(),
   __decorateParam(0, common.Inject(BYMAX_QUEUE_OPTIONS))
 ], exports.ConnectionResolver);
+var WAITING_STATUSES = /* @__PURE__ */ new Set([
+  "connecting",
+  "connect",
+  "reconnecting",
+  "close"
+]);
 function isReplyError(err) {
   return typeof err === "object" && err !== null && err.name === "ReplyError";
 }
@@ -456,6 +475,18 @@ function timeoutException(operation, timeoutMs, cause) {
   if (cause !== void 0) exception.cause = cause;
   return exception;
 }
+function unavailableException(operation, cause) {
+  const exception = new QueueException(
+    QUEUE_ERROR_CODES.CONNECTION_TIMEOUT,
+    common.HttpStatus.INTERNAL_SERVER_ERROR,
+    { operation, reason: "offline" }
+  );
+  exception.cause = cause;
+  return exception;
+}
+function isOfflineRejection(err) {
+  return err instanceof Error && err.message === "Stream isn't writeable and enableOfflineQueue options is false";
+}
 function isCommandTimeout(err) {
   return err instanceof Error && err.message === "Command timed out";
 }
@@ -463,7 +494,8 @@ async function withCommandTimeoutCode(operation, commandTimeoutMs, work) {
   try {
     return await work;
   } catch (err) {
-    throw isCommandTimeout(err) ? timeoutException(operation, commandTimeoutMs(), err) : err;
+    if (isCommandTimeout(err)) throw timeoutException(operation, commandTimeoutMs(), err);
+    throw isOfflineRejection(err) ? unavailableException(operation, err) : err;
   }
 }
 
@@ -479,13 +511,14 @@ function assertValidCron(repeat, queueOptions) {
     });
   }
 }
-var _queues;
+var _queues, _warm;
 exports.QueueService = class QueueService {
   constructor(connection, options) {
     this.connection = connection;
     this.options = options;
     __publicField(this, "logger", new common.Logger(exports.QueueService.name));
     __privateAdd(this, _queues, /* @__PURE__ */ new Map());
+    __privateAdd(this, _warm, /* @__PURE__ */ new Set());
   }
   connection;
   options;
@@ -504,27 +537,38 @@ exports.QueueService = class QueueService {
     __privateGet(this, _queues).set(queueName, queue);
     return queue;
   }
-  enqueueTimeout(operation) {
-    return timeoutException(operation, this.options.enqueueTimeoutMs);
-  }
-  call(operation, work) {
+  call(operation, queueName, run) {
+    let expired = false;
+    const guarded = withDeadline(
+      this.afterReady(queueName).then(() => {
+        if (expired) throw new Error("the call had already timed out");
+        return run();
+      }),
+      this.options.enqueueTimeoutMs,
+      () => {
+        expired = true;
+        return timeoutException(operation, this.options.enqueueTimeoutMs);
+      }
+    );
     return withCommandTimeoutCode(
       operation,
       () => this.connection.getClient().options.commandTimeout ?? this.options.commandTimeoutMs,
-      work
+      guarded
     );
   }
+  async afterReady(queueName) {
+    if (__privateGet(this, _warm).has(queueName)) return;
+    await this.connection.awaitReady();
+    __privateGet(this, _warm).add(queueName);
+  }
   queueFor(queueName) {
     return this.getOrCreateQueue(queueName);
   }
   async enqueue(queueName, jobName, data, options) {
     const job = await this.call(
       "enqueue",
-      withDeadline(
-        this.queueFor(queueName).add(jobName, data, options),
-        this.options.enqueueTimeoutMs,
-        () => this.enqueueTimeout("enqueue")
-      )
+      queueName,
+      () => this.queueFor(queueName).add(jobName, data, options)
     );
     return job;
   }
@@ -543,16 +587,13 @@ exports.QueueService = class QueueService {
     try {
       const created = await this.call(
         "enqueueBulk",
-        withDeadline(
-          this.queueFor(queueName).addBulk(
-            jobs.map((job) => ({
-              name: job.name,
-              data: job.data,
-              ...job.options === void 0 ? {} : { opts: job.options }
-            }))
-          ),
-          this.options.enqueueTimeoutMs,
-          () => this.enqueueTimeout("enqueueBulk")
+        queueName,
+        () => this.queueFor(queueName).addBulk(
+          jobs.map((job) => ({
+            name: job.name,
+            data: job.data,
+            ...job.options === void 0 ? {} : { opts: job.options }
+          }))
         )
       );
       return created;
@@ -570,7 +611,7 @@ exports.QueueService = class QueueService {
     }
   }
   async getJob(queueName, jobId) {
-    const job = await this.call("getJob", this.queueFor(queueName).getJob(jobId));
+    const job = await this.call("getJob", queueName, () => this.queueFor(queueName).getJob(jobId));
     return job ?? null;
   }
   async getJobs(queueName, status, start = 0, end = 50) {
@@ -579,13 +620,18 @@ exports.QueueService = class QueueService {
         reason: `getJobs needs integers with 0 <= start <= end and at most ${String(MAX_JOBS_PAGE_SIZE)} jobs per call`
       });
     }
-    const jobs = await this.call("getJobs", this.queueFor(queueName).getJobs([status], start, end));
+    const jobs = await this.call(
+      "getJobs",
+      queueName,
+      () => this.queueFor(queueName).getJobs([status], start, end)
+    );
     return jobs;
   }
   async getMetrics(queueName) {
     const counts = await this.call(
       "getMetrics",
-      this.queueFor(queueName).getJobCounts("waiting", "active", "completed", "failed", "delayed")
+      queueName,
+      () => this.queueFor(queueName).getJobCounts("waiting", "active", "completed", "failed", "delayed")
     );
     return {
       queue: queueName,
@@ -604,24 +650,37 @@ exports.QueueService = class QueueService {
     if ("pattern" in repeat) assertValidCron(repeat, this.options.queueOptions);
     const job = await this.call(
       "upsertJobScheduler",
-      queue.upsertJobScheduler(schedulerId, repeat, jobTemplate)
+      queueName,
+      () => queue.upsertJobScheduler(schedulerId, repeat, jobTemplate)
     );
     return job;
   }
   async removeJobScheduler(queueName, schedulerId) {
-    return this.call("removeJobScheduler", this.queueFor(queueName).removeJobScheduler(schedulerId));
+    return this.call(
+      "removeJobScheduler",
+      queueName,
+      () => this.queueFor(queueName).removeJobScheduler(schedulerId)
+    );
   }
   async getJobSchedulers(queueName, start = 0, end = 50, asc = true) {
-    return this.call("getJobSchedulers", this.queueFor(queueName).getJobSchedulers(start, end, asc));
+    return this.call(
+      "getJobSchedulers",
+      queueName,
+      () => this.queueFor(queueName).getJobSchedulers(start, end, asc)
+    );
   }
   async pauseQueue(queueName) {
-    await this.call("pauseQueue", this.queueFor(queueName).pause());
+    await this.call("pauseQueue", queueName, () => this.queueFor(queueName).pause());
   }
   async resumeQueue(queueName) {
-    await this.call("resumeQueue", this.queueFor(queueName).resume());
+    await this.call("resumeQueue", queueName, () => this.queueFor(queueName).resume());
   }
   async cleanQueue(queueName, gracePeriodMs, limit, status) {
-    return this.call("cleanQueue", this.queueFor(queueName).clean(gracePeriodMs, limit, status));
+    return this.call(
+      "cleanQueue",
+      queueName,
+      () => this.queueFor(queueName).clean(gracePeriodMs, limit, status)
+    );
   }
   getCachedQueues() {
     return __privateGet(this, _queues);
@@ -631,9 +690,11 @@ exports.QueueService = class QueueService {
       await queue.close().catch(() => void 0);
     }
     __privateGet(this, _queues).clear();
+    __privateGet(this, _warm).clear();
   }
 };
 _queues = new WeakMap();
+_warm = new WeakMap();
 exports.QueueService = __decorateClass([
   common.Injectable(),
   __decorateParam(0, common.Inject(exports.ConnectionResolver)),
@@ -736,6 +797,17 @@ exports.MetricsService = class MetricsService {
 exports.MetricsService = __decorateClass([
   common.Injectable()
 ], exports.MetricsService);
+
+// src/server/utils/abandoned-workers.ts
+var abandoned = /* @__PURE__ */ new WeakSet();
+function abandonWorker(worker) {
+  abandoned.add(worker);
+}
+function isAbandoned(worker) {
+  return abandoned.has(worker);
+}
+
+// src/server/services/worker-registry.service.ts
 var _entries;
 exports.WorkerRegistry = class WorkerRegistry {
   constructor(connection, options) {
@@ -756,7 +828,7 @@ exports.WorkerRegistry = class WorkerRegistry {
     try {
       worker = new bullmq.Worker(
         queueName,
-        toProcessor(handler, options?.jobTimeoutMs),
+        toProcessor(handler, options?.jobTimeoutMs, () => isAbandoned(worker)),
         bullOpts
       );
     } catch (cause) {
@@ -970,7 +1042,7 @@ var JobTimeoutError = class extends Error {
     this.name = "JobTimeoutError";
   }
 };
-function toProcessor(handler, timeoutMs) {
+function adaptHandler(handler, timeoutMs) {
   if (timeoutMs === void 0) return (job, _token, signal) => handler(job, signal);
   return (job, _token, signal) => {
     const own = new AbortController();
@@ -992,6 +1064,16 @@ function toProcessor(handler, timeoutMs) {
     });
   };
 }
+function toProcessor(handler, timeoutMs, abandoned2) {
+  const run = adaptHandler(handler, timeoutMs);
+  return (job, token, signal) => run(job, token, signal).then(
+    (value) => abandoned2() ? new Promise(() => void 0) : value,
+    (error) => {
+      if (abandoned2()) return new Promise(() => void 0);
+      throw error;
+    }
+  );
+}
 var _events, _connections;
 exports.QueueEventsRegistry = class QueueEventsRegistry {
   constructor(connection, options) {
@@ -1170,6 +1252,7 @@ ProcessorDiscoveryService = __decorateClass([
   __decorateParam(1, common.Inject(exports.WorkerRegistry)),
   __decorateParam(2, common.Inject(exports.QueueEventsRegistry))
 ], ProcessorDiscoveryService);
+var FORCE_CLOSE_GRACE_MS = 1e3;
 var DrainTimeoutError = class extends Error {
 };
 var QueueLifecycle = class {
@@ -1203,25 +1286,33 @@ var QueueLifecycle = class {
     await this.closeQueues();
     await this.teardownConnection();
     this.logger.log(
-      `Queue shutdown complete in ${String(Date.now() - (this.startedAt ?? Date.now()))}ms (forced ${String(this.forcedWorkers)} worker(s))`
+      `Queue shutdown complete in ${String(Date.now() - (this.startedAt ?? Date.now()))}ms (${String(this.forcedWorkers)} worker(s) stopped without draining)`
     );
   }
   async closeWorkers(deadline) {
-    let forced = 0;
+    let undrained = 0;
     await Promise.all(
       Array.from(this.workers.getAll(), async ([name, worker]) => {
         try {
-          await bounded(worker.close(), deadline);
+          await bounded(
+            worker.pause().then(() => worker.close()),
+            deadline
+          );
         } catch (cause) {
-          forced++;
+          undrained++;
+          abandonWorker(worker);
+          const stopped = "it is stopped without waiting for its in-flight job, which becomes stalled and is retried";
           this.logger.warn(
-            cause instanceof DrainTimeoutError ? `Worker "${name}" exceeded the ${String(this.resolved.shutdown.drainTimeoutMs)}ms drain budget \u2014 forcing close (${QUEUE_ERROR_CODES.SHUTDOWN_TIMEOUT_EXCEEDED}); the in-flight job becomes stalled and is retried` : `Worker "${name}" failed to close gracefully (${describeError(cause)}) \u2014 forcing close; the in-flight job becomes stalled and is retried`
+            cause instanceof DrainTimeoutError ? `Worker "${name}" exceeded the ${String(this.resolved.shutdown.drainTimeoutMs)}ms drain budget (${QUEUE_ERROR_CODES.SHUTDOWN_TIMEOUT_EXCEEDED}); ${stopped}` : `Worker "${name}" failed to close gracefully (${describeError(cause)}); ${stopped}`
+          );
+          const deadlineError = () => new DrainTimeoutError();
+          await withDeadline(worker.close(true), FORCE_CLOSE_GRACE_MS, deadlineError).catch(
+            () => void 0
           );
-          void worker.close(true).catch(() => void 0);
         }
       })
     );
-    return forced;
+    return undrained;
   }
   async closeQueueEvents(deadline) {
     await Promise.all(

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`.
      *
@@ -1087,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
@@ -1138,11 +1155,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 +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`.
  *
@@ -1273,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.
  *
@@ -1490,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

@@ -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`.
      *
@@ -1087,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
@@ -1138,11 +1155,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 +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`.
  *
@@ -1273,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.
  *
@@ -1490,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.mjs

@@ -248,13 +248,14 @@ function duplicateConnection(client) {
 }
 
 // src/server/services/connection-resolver.service.ts
-var _logger, _client, _options;
+var _logger, _client, _options, _pendingReady;
 var ConnectionResolver = class {
   constructor(options) {
     __privateAdd(this, _logger, new Logger(ConnectionResolver.name));
     __privateAdd(this, _client);
     __privateAdd(this, _options);
     __publicField(this, "mode");
+    __privateAdd(this, _pendingReady);
     __privateSet(this, _options, options);
   }
   async init() {
@@ -310,6 +311,17 @@ var ConnectionResolver = class {
   isOwned() {
     return this.mode === "mode-b-owned";
   }
+  awaitReady() {
+    const client = this.getClient();
+    if (!WAITING_STATUSES.has(client.status)) return Promise.resolve();
+    __privateGet(this, _pendingReady) ?? __privateSet(this, _pendingReady, new Promise((resolve) => {
+      client.once("ready", () => {
+        __privateSet(this, _pendingReady, void 0);
+        resolve();
+      });
+    }));
+    return __privateGet(this, _pendingReady);
+  }
   async teardown() {
     if (this.isOwned() && __privateGet(this, _client)) {
       const client = __privateGet(this, _client);
@@ -330,7 +342,7 @@ var ConnectionResolver = class {
     }
     if (client.options.maxRetriesPerRequest === null) {
       __privateGet(this, _logger).warn(
-        "The shared client has maxRetriesPerRequest: null, so a producer call made while Redis is unreachable waits for as long as the outage lasts; enqueue is bounded by enqueueTimeoutMs, other QueueService calls are not. Give the client a finite limit to fail fast."
+        "The shared client has maxRetriesPerRequest: null, so a command issued while Redis is unreachable stays queued in the client for as long as the outage lasts. QueueService calls are bounded by enqueueTimeoutMs and the caller is released, but the command is not cancelled. Give the client a finite limit to fail fast."
       );
     }
     const probe = duplicateConnection(client);
@@ -380,10 +392,17 @@ var ConnectionResolver = class {
 _logger = new WeakMap();
 _client = new WeakMap();
 _options = new WeakMap();
+_pendingReady = new WeakMap();
 ConnectionResolver = __decorateClass([
   Injectable(),
   __decorateParam(0, Inject(BYMAX_QUEUE_OPTIONS))
 ], ConnectionResolver);
+var WAITING_STATUSES = /* @__PURE__ */ new Set([
+  "connecting",
+  "connect",
+  "reconnecting",
+  "close"
+]);
 function isReplyError(err) {
   return typeof err === "object" && err !== null && err.name === "ReplyError";
 }
@@ -454,6 +473,18 @@ function timeoutException(operation, timeoutMs, cause) {
   if (cause !== void 0) exception.cause = cause;
   return exception;
 }
+function unavailableException(operation, cause) {
+  const exception = new QueueException(
+    QUEUE_ERROR_CODES.CONNECTION_TIMEOUT,
+    HttpStatus.INTERNAL_SERVER_ERROR,
+    { operation, reason: "offline" }
+  );
+  exception.cause = cause;
+  return exception;
+}
+function isOfflineRejection(err) {
+  return err instanceof Error && err.message === "Stream isn't writeable and enableOfflineQueue options is false";
+}
 function isCommandTimeout(err) {
   return err instanceof Error && err.message === "Command timed out";
 }
@@ -461,7 +492,8 @@ async function withCommandTimeoutCode(operation, commandTimeoutMs, work) {
   try {
     return await work;
   } catch (err) {
-    throw isCommandTimeout(err) ? timeoutException(operation, commandTimeoutMs(), err) : err;
+    if (isCommandTimeout(err)) throw timeoutException(operation, commandTimeoutMs(), err);
+    throw isOfflineRejection(err) ? unavailableException(operation, err) : err;
   }
 }
 
@@ -477,13 +509,14 @@ function assertValidCron(repeat, queueOptions) {
     });
   }
 }
-var _queues;
+var _queues, _warm;
 var QueueService = class {
   constructor(connection, options) {
     this.connection = connection;
     this.options = options;
     __publicField(this, "logger", new Logger(QueueService.name));
     __privateAdd(this, _queues, /* @__PURE__ */ new Map());
+    __privateAdd(this, _warm, /* @__PURE__ */ new Set());
   }
   connection;
   options;
@@ -502,27 +535,38 @@ var QueueService = class {
     __privateGet(this, _queues).set(queueName, queue);
     return queue;
   }
-  enqueueTimeout(operation) {
-    return timeoutException(operation, this.options.enqueueTimeoutMs);
-  }
-  call(operation, work) {
+  call(operation, queueName, run) {
+    let expired = false;
+    const guarded = withDeadline(
+      this.afterReady(queueName).then(() => {
+        if (expired) throw new Error("the call had already timed out");
+        return run();
+      }),
+      this.options.enqueueTimeoutMs,
+      () => {
+        expired = true;
+        return timeoutException(operation, this.options.enqueueTimeoutMs);
+      }
+    );
     return withCommandTimeoutCode(
       operation,
       () => this.connection.getClient().options.commandTimeout ?? this.options.commandTimeoutMs,
-      work
+      guarded
     );
   }
+  async afterReady(queueName) {
+    if (__privateGet(this, _warm).has(queueName)) return;
+    await this.connection.awaitReady();
+    __privateGet(this, _warm).add(queueName);
+  }
   queueFor(queueName) {
     return this.getOrCreateQueue(queueName);
   }
   async enqueue(queueName, jobName, data, options) {
     const job = await this.call(
       "enqueue",
-      withDeadline(
-        this.queueFor(queueName).add(jobName, data, options),
-        this.options.enqueueTimeoutMs,
-        () => this.enqueueTimeout("enqueue")
-      )
+      queueName,
+      () => this.queueFor(queueName).add(jobName, data, options)
     );
     return job;
   }
@@ -541,16 +585,13 @@ var QueueService = class {
     try {
       const created = await this.call(
         "enqueueBulk",
-        withDeadline(
-          this.queueFor(queueName).addBulk(
-            jobs.map((job) => ({
-              name: job.name,
-              data: job.data,
-              ...job.options === void 0 ? {} : { opts: job.options }
-            }))
-          ),
-          this.options.enqueueTimeoutMs,
-          () => this.enqueueTimeout("enqueueBulk")
+        queueName,
+        () => this.queueFor(queueName).addBulk(
+          jobs.map((job) => ({
+            name: job.name,
+            data: job.data,
+            ...job.options === void 0 ? {} : { opts: job.options }
+          }))
         )
       );
       return created;
@@ -568,7 +609,7 @@ var QueueService = class {
     }
   }
   async getJob(queueName, jobId) {
-    const job = await this.call("getJob", this.queueFor(queueName).getJob(jobId));
+    const job = await this.call("getJob", queueName, () => this.queueFor(queueName).getJob(jobId));
     return job ?? null;
   }
   async getJobs(queueName, status, start = 0, end = 50) {
@@ -577,13 +618,18 @@ var QueueService = class {
         reason: `getJobs needs integers with 0 <= start <= end and at most ${String(MAX_JOBS_PAGE_SIZE)} jobs per call`
       });
     }
-    const jobs = await this.call("getJobs", this.queueFor(queueName).getJobs([status], start, end));
+    const jobs = await this.call(
+      "getJobs",
+      queueName,
+      () => this.queueFor(queueName).getJobs([status], start, end)
+    );
     return jobs;
   }
   async getMetrics(queueName) {
     const counts = await this.call(
       "getMetrics",
-      this.queueFor(queueName).getJobCounts("waiting", "active", "completed", "failed", "delayed")
+      queueName,
+      () => this.queueFor(queueName).getJobCounts("waiting", "active", "completed", "failed", "delayed")
     );
     return {
       queue: queueName,
@@ -602,24 +648,37 @@ var QueueService = class {
     if ("pattern" in repeat) assertValidCron(repeat, this.options.queueOptions);
     const job = await this.call(
       "upsertJobScheduler",
-      queue.upsertJobScheduler(schedulerId, repeat, jobTemplate)
+      queueName,
+      () => queue.upsertJobScheduler(schedulerId, repeat, jobTemplate)
     );
     return job;
   }
   async removeJobScheduler(queueName, schedulerId) {
-    return this.call("removeJobScheduler", this.queueFor(queueName).removeJobScheduler(schedulerId));
+    return this.call(
+      "removeJobScheduler",
+      queueName,
+      () => this.queueFor(queueName).removeJobScheduler(schedulerId)
+    );
   }
   async getJobSchedulers(queueName, start = 0, end = 50, asc = true) {
-    return this.call("getJobSchedulers", this.queueFor(queueName).getJobSchedulers(start, end, asc));
+    return this.call(
+      "getJobSchedulers",
+      queueName,
+      () => this.queueFor(queueName).getJobSchedulers(start, end, asc)
+    );
   }
   async pauseQueue(queueName) {
-    await this.call("pauseQueue", this.queueFor(queueName).pause());
+    await this.call("pauseQueue", queueName, () => this.queueFor(queueName).pause());
   }
   async resumeQueue(queueName) {
-    await this.call("resumeQueue", this.queueFor(queueName).resume());
+    await this.call("resumeQueue", queueName, () => this.queueFor(queueName).resume());
   }
   async cleanQueue(queueName, gracePeriodMs, limit, status) {
-    return this.call("cleanQueue", this.queueFor(queueName).clean(gracePeriodMs, limit, status));
+    return this.call(
+      "cleanQueue",
+      queueName,
+      () => this.queueFor(queueName).clean(gracePeriodMs, limit, status)
+    );
   }
   getCachedQueues() {
     return __privateGet(this, _queues);
@@ -629,9 +688,11 @@ var QueueService = class {
       await queue.close().catch(() => void 0);
     }
     __privateGet(this, _queues).clear();
+    __privateGet(this, _warm).clear();
   }
 };
 _queues = new WeakMap();
+_warm = new WeakMap();
 QueueService = __decorateClass([
   Injectable(),
   __decorateParam(0, Inject(ConnectionResolver)),
@@ -734,6 +795,17 @@ var MetricsService = class {
 MetricsService = __decorateClass([
   Injectable()
 ], MetricsService);
+
+// src/server/utils/abandoned-workers.ts
+var abandoned = /* @__PURE__ */ new WeakSet();
+function abandonWorker(worker) {
+  abandoned.add(worker);
+}
+function isAbandoned(worker) {
+  return abandoned.has(worker);
+}
+
+// src/server/services/worker-registry.service.ts
 var _entries;
 var WorkerRegistry = class {
   constructor(connection, options) {
@@ -754,7 +826,7 @@ var WorkerRegistry = class {
     try {
       worker = new Worker(
         queueName,
-        toProcessor(handler, options?.jobTimeoutMs),
+        toProcessor(handler, options?.jobTimeoutMs, () => isAbandoned(worker)),
         bullOpts
       );
     } catch (cause) {
@@ -968,7 +1040,7 @@ var JobTimeoutError = class extends Error {
     this.name = "JobTimeoutError";
   }
 };
-function toProcessor(handler, timeoutMs) {
+function adaptHandler(handler, timeoutMs) {
   if (timeoutMs === void 0) return (job, _token, signal) => handler(job, signal);
   return (job, _token, signal) => {
     const own = new AbortController();
@@ -990,6 +1062,16 @@ function toProcessor(handler, timeoutMs) {
     });
   };
 }
+function toProcessor(handler, timeoutMs, abandoned2) {
+  const run = adaptHandler(handler, timeoutMs);
+  return (job, token, signal) => run(job, token, signal).then(
+    (value) => abandoned2() ? new Promise(() => void 0) : value,
+    (error) => {
+      if (abandoned2()) return new Promise(() => void 0);
+      throw error;
+    }
+  );
+}
 var _events, _connections;
 var QueueEventsRegistry = class {
   constructor(connection, options) {
@@ -1168,6 +1250,7 @@ ProcessorDiscoveryService = __decorateClass([
   __decorateParam(1, Inject(WorkerRegistry)),
   __decorateParam(2, Inject(QueueEventsRegistry))
 ], ProcessorDiscoveryService);
+var FORCE_CLOSE_GRACE_MS = 1e3;
 var DrainTimeoutError = class extends Error {
 };
 var QueueLifecycle = class {
@@ -1201,25 +1284,33 @@ var QueueLifecycle = class {
     await this.closeQueues();
     await this.teardownConnection();
     this.logger.log(
-      `Queue shutdown complete in ${String(Date.now() - (this.startedAt ?? Date.now()))}ms (forced ${String(this.forcedWorkers)} worker(s))`
+      `Queue shutdown complete in ${String(Date.now() - (this.startedAt ?? Date.now()))}ms (${String(this.forcedWorkers)} worker(s) stopped without draining)`
     );
   }
   async closeWorkers(deadline) {
-    let forced = 0;
+    let undrained = 0;
     await Promise.all(
       Array.from(this.workers.getAll(), async ([name, worker]) => {
         try {
-          await bounded(worker.close(), deadline);
+          await bounded(
+            worker.pause().then(() => worker.close()),
+            deadline
+          );
         } catch (cause) {
-          forced++;
+          undrained++;
+          abandonWorker(worker);
+          const stopped = "it is stopped without waiting for its in-flight job, which becomes stalled and is retried";
           this.logger.warn(
-            cause instanceof DrainTimeoutError ? `Worker "${name}" exceeded the ${String(this.resolved.shutdown.drainTimeoutMs)}ms drain budget \u2014 forcing close (${QUEUE_ERROR_CODES.SHUTDOWN_TIMEOUT_EXCEEDED}); the in-flight job becomes stalled and is retried` : `Worker "${name}" failed to close gracefully (${describeError(cause)}) \u2014 forcing close; the in-flight job becomes stalled and is retried`
+            cause instanceof DrainTimeoutError ? `Worker "${name}" exceeded the ${String(this.resolved.shutdown.drainTimeoutMs)}ms drain budget (${QUEUE_ERROR_CODES.SHUTDOWN_TIMEOUT_EXCEEDED}); ${stopped}` : `Worker "${name}" failed to close gracefully (${describeError(cause)}); ${stopped}`
+          );
+          const deadlineError = () => new DrainTimeoutError();
+          await withDeadline(worker.close(true), FORCE_CLOSE_GRACE_MS, deadlineError).catch(
+            () => void 0
           );
-          void worker.close(true).catch(() => void 0);
         }
       })
     );
-    return forced;
+    return undrained;
   }
   async closeQueueEvents(deadline) {
     await Promise.all(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-queue",
-  "version": "1.2.14",
+  "version": "1.2.15",
   "description": "NestJS dynamic module wrapping BullMQ — typed jobs, flows, job schedulers, deduplication, OpenTelemetry, graceful shutdown",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",