@bymax-one/nest-queue 1.2.8 → 1.2.10

package/CHANGELOG.md

@@ -11,6 +11,80 @@ versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.2.10] — 2026-11-01
+
+Action required only if code relies on the status of a failed schedule: `upsertJobScheduler` no
+longer reports every failure as `INVALID_REPEAT_OPTIONS` (400), see the Apply note. Healthy use is
+unchanged. The public API, the types (the declaration files differ only in JSDoc comments) and the
+peer ranges are unchanged. Measured with `diff -r` of a fresh build against the unpacked 1.2.9 tarball,
+the runtime bundles (`index.mjs`, `index.cjs`) differ in code.
+
+### Fixed
+
+- **A failed schedule write was reported as an invalid cron.** `upsertJobScheduler` turned every
+  error without a string `code` into `INVALID_REPEAT_OPTIONS` (400, "pattern must be a valid cron
+  expression"). A Redis reply error carries no `code`, so a replica refusing the write (`READONLY`),
+  an out-of-memory server (`OOM`) or a missing login (`NOAUTH`) was reported as the caller's mistake,
+  and the caller was told not to retry. The pattern is now checked first with BullMQ's own repeat
+  strategy, a pure function with no Redis call, and only a pattern it refuses is
+  `INVALID_REPEAT_OPTIONS`; every failure of the write itself reaches the caller as it is. A
+  consumer-supplied `settings.repeatStrategy` replaces the parser, so the pattern is not checked.
+  A malformed pattern on a schedule whose iteration `limit` is already reached is now rejected as
+  well; BullMQ's own upsert returns before parsing such a schedule and silently accepts it.
+- **A failing `@OnWorkerEvent` or `@OnQueueEvent` handler could end the process.** The listener was
+  bound straight onto the emitter, which neither awaits it nor catches a throw: an async handler
+  that rejected became an unhandled rejection, which ends a Node process by default, and a
+  synchronous throw was re-emitted as `error`. The failure is now logged with the handler's name
+  and the code `queue.event_handler_failed`, and the process carries on.
+- **`drainOnShutdown` failed silently.** A queue whose drain failed kept its waiting jobs with no
+  trace in the log; it now logs a warning naming the queue and the cause.
+- **A worker whose close failed was logged as a drain timeout.** Any rejection of the graceful
+  close was reported as "exceeded the drain budget"; a real error, such as a lost connection, now
+  has its own message with the cause. The worker is force-closed either way.
+
+### Documentation
+
+- **A duplicate does not add a job.** The README and the JSDoc of `enqueue`, `enqueueBulk` and the
+  flow methods now say that when a custom `jobId` already exists, or a `deduplication` rule keeps
+  the job already there, BullMQ answers with the id of the existing job together with the data of
+  this call, so the returned object does not describe what is stored; `getJob` returns it.
+- **The scheduler and event-handler behaviour above is described in the README.**
+- **Correction to 1.2.9.** On 1.2.8 only the `FlowProducer` listener could end the process; on
+  `Queue`, `Worker` and `QueueEvents` BullMQ's wrapper re-emitted the `TypeError` and the error was
+  reported with a misleading log line. 1.2.9 fixes both.
+
+#### Apply to a derived backend
+
+- If you branch on `INVALID_REPEAT_OPTIONS` to detect any failure of `upsertJobScheduler`, change
+  it: a valid pattern whose write fails now throws the original error (a Redis reply error, a
+  connection error), not a 400 `QueueException`. An unparseable pattern is still
+  `INVALID_REPEAT_OPTIONS`, now thrown before Redis is asked.
+- A listener that fails is now logged instead of ending the process. If something relied on the
+  crash to stop a faulty deploy, watch for the log code `queue.event_handler_failed`.
+
+---
+
+## [1.2.9] — 2026-11-01
+
+No action required: behaviour for an `Error` with a string `message` is unchanged, and the public API, the types
+(`index.d.ts` and `index.d.cts` are identical) and the peer ranges are unchanged. Measured with
+`diff -r` of a fresh build against the unpacked 1.2.8 tarball, only the two runtime bundles
+(`index.mjs`, `index.cjs`) differ.
+
+### Fixed
+
+- **The fallback `error` listener no longer throws on an emission that is not an `Error`.** The
+  listener the library attaches to every `Queue`, `Worker` and `QueueEvents`, and to the `FlowProducer` when flows are enabled, read
+  `err.message` directly, so `emit('error', undefined)` or `emit('error', null)` threw a `TypeError`
+  out of the listener, and out of `emit` to its caller, which can end the process. It now logs
+  whatever value arrived, falling back to a fixed phrase for one it cannot print.
+- **A rejected `enqueueBulk` with a non-`Error` reason still produces `BULK_ENQUEUE_FAILED`.**
+  The cause was read with `(err as Error).message`, which threw a `TypeError` for a `null` or
+  `undefined` rejection, replacing the typed exception; it now carries a string cause for any
+  rejected value.
+
+---
+
 ## [1.2.8] — 2026-11-01
 
 No action required: behaviour, the public API, the types and the peer ranges are unchanged.
@@ -747,7 +821,9 @@ v6 peer range.
 
 ---
 
-[Unreleased]: https://github.com/bymaxone/nest-queue/compare/v1.2.8...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-queue/compare/v1.2.10...HEAD
+[1.2.10]: https://github.com/bymaxone/nest-queue/compare/v1.2.9...v1.2.10
+[1.2.9]: https://github.com/bymaxone/nest-queue/compare/v1.2.8...v1.2.9
 [1.2.8]: https://github.com/bymaxone/nest-queue/compare/v1.2.7...v1.2.8
 [1.2.7]: https://github.com/bymaxone/nest-queue/compare/v1.2.6...v1.2.7
 [1.2.6]: https://github.com/bymaxone/nest-queue/compare/v1.2.5...v1.2.6

package/README.md

@@ -557,6 +557,8 @@ onFailed(job: Job | undefined, err: Error): void {
 }
 ```
 
+A listener that throws, or returns a promise that rejects, is logged with the handler's name and the code `queue.event_handler_failed` and the process carries on; it is never an unhandled rejection. Handle the error inside the listener when the failure matters.
+
 ### `@OnQueueEvent(eventName)`
 
 Listens to BullMQ `QueueEvents` (global, cross-process events). The library opens one shared `QueueEvents` connection per queue when it discovers the first listener for it; there is no option to enable.
@@ -602,6 +604,7 @@ const schedulers = await this.queue.getJobSchedulers('notifications')
 
 Cron-with-seconds (6-field patterns) is supported. Patterns are validated by BullMQ's
 own `cron-parser`, not a hand-rolled regex.
+A pattern the parser rejects is `INVALID_REPEAT_OPTIONS` (400) before Redis is asked. Every other failure of the upsert, such as a read-only replica or a lost connection, reaches you as it is.
 
 ---
 
@@ -643,6 +646,10 @@ await this.queue.enqueue(
 )
 ```
 
+### A duplicate does not add a job
+
+When a custom `jobId` already exists, or a `deduplication` rule keeps the job that is already there (a rule with `replace` swaps it for the new one instead), `enqueue`, `enqueueBulk` and the flow methods add nothing: BullMQ answers with the id of the **existing** job together with the data and options of **this** call, so the returned object does not describe what is stored. Call `QueueService.getJob` when you need the stored job.
+
 ### OpenTelemetry
 
 Pass a `bullmq-otel` telemetry instance (optional peer dep) to trace spans from `enqueue` through the handler:

package/dist/server/index.cjs

@@ -368,17 +368,36 @@ function validateJobSchedulerOptions(repeat) {
   }
 }
 
+// src/server/utils/describe-error.ts
+function describeError(cause) {
+  try {
+    if (typeof cause === "object" && cause !== null && "message" in cause) {
+      if (typeof cause.message === "string") return cause.message;
+    }
+    return String(cause);
+  } catch {
+    return "unknown error";
+  }
+}
+
 // src/server/utils/attach-error-listener.ts
 function attachDefaultErrorListener(emitter, logger, kind, queueName) {
   emitter.on("error", (err) => {
-    logger.error(`${kind} for queue "${queueName}" emitted an error: ${err.message}`);
+    logger.error(`${kind} for queue "${queueName}" emitted an error: ${describeError(err)}`);
   });
 }
 
 // src/server/services/queue.service.ts
 var MAX_BULK_SIZE = 1e3;
-function isOperationalError(err) {
-  return typeof err?.code === "string";
+function assertValidCron(repeat, queueOptions) {
+  if (queueOptions.settings?.repeatStrategy !== void 0) return;
+  try {
+    bullmq.defaultRepeatStrategy(Date.now(), repeat);
+  } catch {
+    throw new QueueException(QUEUE_ERROR_CODES.INVALID_REPEAT_OPTIONS, common.HttpStatus.BAD_REQUEST, {
+      reason: "pattern must be a valid cron expression (5- or 6-field)"
+    });
+  }
 }
 var _queues;
 exports.QueueService = class QueueService {
@@ -456,7 +475,11 @@ exports.QueueService = class QueueService {
    * @param jobName - Job identifier used by `@Process` to dispatch.
    * @param data - Typed job payload.
    * @param options - Per-job BullMQ options (priority, delay, `jobId`, `deduplication`, ...).
-   * @returns The created job.
+   * @returns The job BullMQ returned. When a custom `jobId` already exists, or a `deduplication`
+   *   rule keeps the job already there (one with `replace` swaps it for the new job), nothing new
+   *   is added: BullMQ answers with the id of the EXISTING job and the data and options of THIS
+   *   call, so the returned object does not describe what is stored. Call
+   *   {@link QueueService.getJob} when you need the stored job.
    * @example Throttle: at most one reindex per term every 5 seconds. Both variable
    *   fields are percent-encoded, so no other tenant/term pair can build this key.
    *   const dedupId = `${encodeURIComponent(tenantId)}:reindex:${encodeURIComponent(term)}`
@@ -476,6 +499,9 @@ exports.QueueService = class QueueService {
    *
    * @param queueName - Target queue.
    * @param jobs - Job descriptors (length must not exceed the bulk size cap).
+   * @returns The jobs BullMQ returned, in input order. An entry whose custom `jobId` already
+   *   exists is not added again: it carries the EXISTING id with the data of this call, as for
+   *   {@link QueueService.enqueue}.
    */
   async enqueueBulk(queueName, jobs) {
     if (jobs.length > MAX_BULK_SIZE) {
@@ -503,7 +529,7 @@ exports.QueueService = class QueueService {
         QUEUE_ERROR_CODES.BULK_ENQUEUE_FAILED,
         common.HttpStatus.INTERNAL_SERVER_ERROR,
         {
-          cause: err.message
+          cause: describeError(err)
         }
       );
     }
@@ -556,9 +582,9 @@ exports.QueueService = class QueueService {
    * never duplicates it. This supersedes the repeatable-jobs surface removed in
    * BullMQ v6.
    *
-   * The schedule is structurally validated first; the cron string itself is
-   * parsed by BullMQ at registration time, and a parse failure is rethrown as
-   * `INVALID_REPEAT_OPTIONS` (400).
+   * The schedule is validated first, and a cron pattern BullMQ's parser rejects
+   * is `INVALID_REPEAT_OPTIONS` (400) before Redis is asked; any other failure
+   * propagates as it is.
    *
    * @param queueName - Target queue.
    * @param schedulerId - Stable, unique scheduler identifier (the upsert key).
@@ -575,17 +601,7 @@ exports.QueueService = class QueueService {
       data: template?.data ?? {},
       ...template?.opts === void 0 ? {} : { opts: template.opts }
     };
-    if ("pattern" in repeat) {
-      try {
-        const job2 = await queue.upsertJobScheduler(schedulerId, repeat, jobTemplate);
-        return job2;
-      } catch (err) {
-        if (isOperationalError(err)) throw err;
-        throw new QueueException(QUEUE_ERROR_CODES.INVALID_REPEAT_OPTIONS, common.HttpStatus.BAD_REQUEST, {
-          reason: "pattern must be a valid cron expression (5- or 6-field)"
-        });
-      }
-    }
+    if ("pattern" in repeat) assertValidCron(repeat, this.options.queueOptions);
     const job = await queue.upsertJobScheduler(schedulerId, repeat, jobTemplate);
     return job;
   }
@@ -687,6 +703,9 @@ exports.FlowService = class FlowService {
    *
    * @param flow - Flow tree definition.
    * @returns The root `JobNode` containing the created job and its children.
+   *   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.
    */
   async add(flow) {
@@ -697,6 +716,7 @@ exports.FlowService = 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.
    */
   async addBulk(flows) {
@@ -809,20 +829,6 @@ exports.MetricsService = class MetricsService {
 exports.MetricsService = __decorateClass([
   common.Injectable()
 ], exports.MetricsService);
-
-// src/server/utils/describe-error.ts
-function describeError(cause) {
-  try {
-    if (typeof cause === "object" && cause !== null && "message" in cause) {
-      if (typeof cause.message === "string") return cause.message;
-    }
-    return String(cause);
-  } catch {
-    return "unknown error";
-  }
-}
-
-// src/server/services/worker-registry.service.ts
 var _entries;
 exports.WorkerRegistry = class WorkerRegistry {
   constructor(connection, options) {
@@ -1209,6 +1215,7 @@ var WORKER_EVENT_LISTENERS_METADATA_KEY = /* @__PURE__ */ Symbol("bymax_queue:wo
 var QUEUE_EVENT_LISTENERS_METADATA_KEY = /* @__PURE__ */ Symbol("bymax_queue:queue_event_listeners");
 
 // src/server/services/processor-discovery.service.ts
+var EVENT_HANDLER_FAILED = "queue.event_handler_failed";
 var ProcessorDiscoveryService = class {
   constructor(discovery, workers, events) {
     this.discovery = discovery;
@@ -1303,7 +1310,14 @@ var ProcessorDiscoveryService = class {
     for (const { eventName, methodKey } of workerListeners) {
       const method = instance[methodKey];
       if (typeof method === "function") {
-        workerEmitter.on(eventName, method.bind(instance));
+        workerEmitter.on(
+          eventName,
+          this.guardListener(instance, method, {
+            decorator: "@OnWorkerEvent",
+            eventName,
+            methodKey
+          })
+        );
       }
     }
     const queueListeners = Reflect.getOwnMetadata(QUEUE_EVENT_LISTENERS_METADATA_KEY, ctor) ?? [];
@@ -1313,11 +1327,46 @@ var ProcessorDiscoveryService = class {
       for (const { eventName, methodKey } of queueListeners) {
         const method = instance[methodKey];
         if (typeof method === "function") {
-          qeEmitter.on(eventName, method.bind(instance));
+          qeEmitter.on(
+            eventName,
+            this.guardListener(instance, method, {
+              decorator: "@OnQueueEvent",
+              eventName,
+              methodKey
+            })
+          );
         }
       }
     }
   }
+  /**
+   * Bind an event listener so a failing handler is reported instead of escaping.
+   *
+   * An `EventEmitter` neither awaits a listener nor catches its throw: a rejected promise becomes
+   * an `unhandledRejection`, which ends the process by default, and BullMQ re-emits a synchronous
+   * throw as `error`. A failing handler is the consumer's defect, never a reason to
+   * stop the application, but it must still be visible, so the failure is logged with the handler
+   * and a stable code and the process carries on.
+   *
+   * @param instance - The provider the handler belongs to (its `this`).
+   * @param method - The handler method.
+   * @param origin - Which decorator, event and method name the listener comes from.
+   * @returns The listener to register on the emitter.
+   */
+  guardListener(instance, method, origin) {
+    const report = (cause) => {
+      this.logger.error(
+        `${origin.decorator}("${origin.eventName}") handler ${instance.constructor.name}.${String(origin.methodKey)} failed (${EVENT_HANDLER_FAILED}): ${describeError(cause)}`
+      );
+    };
+    return (...args) => {
+      try {
+        void Promise.resolve(method.apply(instance, args)).catch(report);
+      } catch (cause) {
+        report(cause);
+      }
+    };
+  }
 };
 ProcessorDiscoveryService = __decorateClass([
   common.Injectable(),
@@ -1325,6 +1374,8 @@ ProcessorDiscoveryService = __decorateClass([
   __decorateParam(1, common.Inject(exports.WorkerRegistry)),
   __decorateParam(2, common.Inject(exports.QueueEventsRegistry))
 ], ProcessorDiscoveryService);
+var DrainTimeoutError = class extends Error {
+};
 var QueueLifecycle = class {
   constructor(workers, events, queues, flow, connection, resolved) {
     this.workers = workers;
@@ -1370,10 +1421,10 @@ var QueueLifecycle = class {
     for (const [name, worker] of this.workers.getAll()) {
       try {
         await this.closeWorkerWithTimeout(worker, drainTimeoutMs);
-      } catch {
+      } catch (cause) {
         forced++;
         this.logger.warn(
-          `Worker "${name}" exceeded the ${String(drainTimeoutMs)}ms drain budget \u2014 forcing close (${QUEUE_ERROR_CODES.SHUTDOWN_TIMEOUT_EXCEEDED}); the in-flight job becomes stalled and is retried`
+          cause instanceof DrainTimeoutError ? `Worker "${name}" exceeded the ${String(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`
         );
         void worker.close(true).catch(() => void 0);
       }
@@ -1397,7 +1448,7 @@ var QueueLifecycle = class {
         closed,
         new Promise((_resolve, reject) => {
           timer = setTimeout(() => {
-            reject(new Error("drain timeout"));
+            reject(new DrainTimeoutError());
           }, timeoutMs);
         })
       ]);
@@ -1436,8 +1487,12 @@ var QueueLifecycle = class {
    */
   async drainQueuesIfRequested() {
     if (!this.resolved.shutdown.drainOnShutdown) return;
-    for (const [, queue] of this.queues.getCachedQueues()) {
-      await queue.drain().catch(() => void 0);
+    for (const [name, queue] of this.queues.getCachedQueues()) {
+      await queue.drain().catch((cause) => {
+        this.logger.warn(
+          `Queue "${name}" could not be drained on shutdown (drainOnShutdown): ${describeError(cause)}; its waiting jobs remain`
+        );
+      });
     }
   }
   /** Close the flow producer (idempotent), swallowing any failure. */

package/dist/server/index.d.cts

@@ -453,7 +453,11 @@ declare class QueueService {
      * @param jobName - Job identifier used by `@Process` to dispatch.
      * @param data - Typed job payload.
      * @param options - Per-job BullMQ options (priority, delay, `jobId`, `deduplication`, ...).
-     * @returns The created job.
+     * @returns The job BullMQ returned. When a custom `jobId` already exists, or a `deduplication`
+     *   rule keeps the job already there (one with `replace` swaps it for the new job), nothing new
+     *   is added: BullMQ answers with the id of the EXISTING job and the data and options of THIS
+     *   call, so the returned object does not describe what is stored. Call
+     *   {@link QueueService.getJob} when you need the stored job.
      * @example Throttle: at most one reindex per term every 5 seconds. Both variable
      *   fields are percent-encoded, so no other tenant/term pair can build this key.
      *   const dedupId = `${encodeURIComponent(tenantId)}:reindex:${encodeURIComponent(term)}`
@@ -470,6 +474,9 @@ declare class QueueService {
      *
      * @param queueName - Target queue.
      * @param jobs - Job descriptors (length must not exceed the bulk size cap).
+     * @returns The jobs BullMQ returned, in input order. An entry whose custom `jobId` already
+     *   exists is not added again: it carries the EXISTING id with the data of this call, as for
+     *   {@link QueueService.enqueue}.
      */
     enqueueBulk<TData = unknown, TResult = unknown>(queueName: string, jobs: readonly BulkJob<TData>[]): Promise<TypedJob<TData, TResult>[]>;
     /**
@@ -501,9 +508,9 @@ declare class QueueService {
      * never duplicates it. This supersedes the repeatable-jobs surface removed in
      * BullMQ v6.
      *
-     * The schedule is structurally validated first; the cron string itself is
-     * parsed by BullMQ at registration time, and a parse failure is rethrown as
-     * `INVALID_REPEAT_OPTIONS` (400).
+     * The schedule is validated first, and a cron pattern BullMQ's parser rejects
+     * is `INVALID_REPEAT_OPTIONS` (400) before Redis is asked; any other failure
+     * propagates as it is.
      *
      * @param queueName - Target queue.
      * @param schedulerId - Stable, unique scheduler identifier (the upsert key).
@@ -607,6 +614,9 @@ declare class FlowService {
      *
      * @param flow - Flow tree definition.
      * @returns The root `JobNode` containing the created job and its children.
+     *   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.
      */
     add(flow: FlowJob): Promise<JobNode>;
@@ -615,6 +625,7 @@ 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.
      */
     addBulk(flows: readonly FlowJob[]): Promise<JobNode[]>;

package/dist/server/index.d.ts

@@ -453,7 +453,11 @@ declare class QueueService {
      * @param jobName - Job identifier used by `@Process` to dispatch.
      * @param data - Typed job payload.
      * @param options - Per-job BullMQ options (priority, delay, `jobId`, `deduplication`, ...).
-     * @returns The created job.
+     * @returns The job BullMQ returned. When a custom `jobId` already exists, or a `deduplication`
+     *   rule keeps the job already there (one with `replace` swaps it for the new job), nothing new
+     *   is added: BullMQ answers with the id of the EXISTING job and the data and options of THIS
+     *   call, so the returned object does not describe what is stored. Call
+     *   {@link QueueService.getJob} when you need the stored job.
      * @example Throttle: at most one reindex per term every 5 seconds. Both variable
      *   fields are percent-encoded, so no other tenant/term pair can build this key.
      *   const dedupId = `${encodeURIComponent(tenantId)}:reindex:${encodeURIComponent(term)}`
@@ -470,6 +474,9 @@ declare class QueueService {
      *
      * @param queueName - Target queue.
      * @param jobs - Job descriptors (length must not exceed the bulk size cap).
+     * @returns The jobs BullMQ returned, in input order. An entry whose custom `jobId` already
+     *   exists is not added again: it carries the EXISTING id with the data of this call, as for
+     *   {@link QueueService.enqueue}.
      */
     enqueueBulk<TData = unknown, TResult = unknown>(queueName: string, jobs: readonly BulkJob<TData>[]): Promise<TypedJob<TData, TResult>[]>;
     /**
@@ -501,9 +508,9 @@ declare class QueueService {
      * never duplicates it. This supersedes the repeatable-jobs surface removed in
      * BullMQ v6.
      *
-     * The schedule is structurally validated first; the cron string itself is
-     * parsed by BullMQ at registration time, and a parse failure is rethrown as
-     * `INVALID_REPEAT_OPTIONS` (400).
+     * The schedule is validated first, and a cron pattern BullMQ's parser rejects
+     * is `INVALID_REPEAT_OPTIONS` (400) before Redis is asked; any other failure
+     * propagates as it is.
      *
      * @param queueName - Target queue.
      * @param schedulerId - Stable, unique scheduler identifier (the upsert key).
@@ -607,6 +614,9 @@ declare class FlowService {
      *
      * @param flow - Flow tree definition.
      * @returns The root `JobNode` containing the created job and its children.
+     *   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.
      */
     add(flow: FlowJob): Promise<JobNode>;
@@ -615,6 +625,7 @@ 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.
      */
     addBulk(flows: readonly FlowJob[]): Promise<JobNode[]>;

package/dist/server/index.mjs

@@ -1,7 +1,7 @@
 import { Injectable, Inject, ConfigurableModuleBuilder, Module, HttpStatus, Logger, HttpException } from '@nestjs/common';
 import { DiscoveryService, DiscoveryModule } from '@nestjs/core';
 import { Redis } from 'ioredis';
-import { Worker, QueueEvents, Queue, FlowProducer } from 'bullmq';
+import { Worker, QueueEvents, Queue, FlowProducer, defaultRepeatStrategy } from 'bullmq';
 import { isAbsolute, extname } from 'path';
 
 var __defProp = Object.defineProperty;
@@ -366,17 +366,36 @@ function validateJobSchedulerOptions(repeat) {
   }
 }
 
+// src/server/utils/describe-error.ts
+function describeError(cause) {
+  try {
+    if (typeof cause === "object" && cause !== null && "message" in cause) {
+      if (typeof cause.message === "string") return cause.message;
+    }
+    return String(cause);
+  } catch {
+    return "unknown error";
+  }
+}
+
 // src/server/utils/attach-error-listener.ts
 function attachDefaultErrorListener(emitter, logger, kind, queueName) {
   emitter.on("error", (err) => {
-    logger.error(`${kind} for queue "${queueName}" emitted an error: ${err.message}`);
+    logger.error(`${kind} for queue "${queueName}" emitted an error: ${describeError(err)}`);
   });
 }
 
 // src/server/services/queue.service.ts
 var MAX_BULK_SIZE = 1e3;
-function isOperationalError(err) {
-  return typeof err?.code === "string";
+function assertValidCron(repeat, queueOptions) {
+  if (queueOptions.settings?.repeatStrategy !== void 0) return;
+  try {
+    defaultRepeatStrategy(Date.now(), repeat);
+  } catch {
+    throw new QueueException(QUEUE_ERROR_CODES.INVALID_REPEAT_OPTIONS, HttpStatus.BAD_REQUEST, {
+      reason: "pattern must be a valid cron expression (5- or 6-field)"
+    });
+  }
 }
 var _queues;
 var QueueService = class {
@@ -454,7 +473,11 @@ var QueueService = class {
    * @param jobName - Job identifier used by `@Process` to dispatch.
    * @param data - Typed job payload.
    * @param options - Per-job BullMQ options (priority, delay, `jobId`, `deduplication`, ...).
-   * @returns The created job.
+   * @returns The job BullMQ returned. When a custom `jobId` already exists, or a `deduplication`
+   *   rule keeps the job already there (one with `replace` swaps it for the new job), nothing new
+   *   is added: BullMQ answers with the id of the EXISTING job and the data and options of THIS
+   *   call, so the returned object does not describe what is stored. Call
+   *   {@link QueueService.getJob} when you need the stored job.
    * @example Throttle: at most one reindex per term every 5 seconds. Both variable
    *   fields are percent-encoded, so no other tenant/term pair can build this key.
    *   const dedupId = `${encodeURIComponent(tenantId)}:reindex:${encodeURIComponent(term)}`
@@ -474,6 +497,9 @@ var QueueService = class {
    *
    * @param queueName - Target queue.
    * @param jobs - Job descriptors (length must not exceed the bulk size cap).
+   * @returns The jobs BullMQ returned, in input order. An entry whose custom `jobId` already
+   *   exists is not added again: it carries the EXISTING id with the data of this call, as for
+   *   {@link QueueService.enqueue}.
    */
   async enqueueBulk(queueName, jobs) {
     if (jobs.length > MAX_BULK_SIZE) {
@@ -501,7 +527,7 @@ var QueueService = class {
         QUEUE_ERROR_CODES.BULK_ENQUEUE_FAILED,
         HttpStatus.INTERNAL_SERVER_ERROR,
         {
-          cause: err.message
+          cause: describeError(err)
         }
       );
     }
@@ -554,9 +580,9 @@ var QueueService = class {
    * never duplicates it. This supersedes the repeatable-jobs surface removed in
    * BullMQ v6.
    *
-   * The schedule is structurally validated first; the cron string itself is
-   * parsed by BullMQ at registration time, and a parse failure is rethrown as
-   * `INVALID_REPEAT_OPTIONS` (400).
+   * The schedule is validated first, and a cron pattern BullMQ's parser rejects
+   * is `INVALID_REPEAT_OPTIONS` (400) before Redis is asked; any other failure
+   * propagates as it is.
    *
    * @param queueName - Target queue.
    * @param schedulerId - Stable, unique scheduler identifier (the upsert key).
@@ -573,17 +599,7 @@ var QueueService = class {
       data: template?.data ?? {},
       ...template?.opts === void 0 ? {} : { opts: template.opts }
     };
-    if ("pattern" in repeat) {
-      try {
-        const job2 = await queue.upsertJobScheduler(schedulerId, repeat, jobTemplate);
-        return job2;
-      } catch (err) {
-        if (isOperationalError(err)) throw err;
-        throw new QueueException(QUEUE_ERROR_CODES.INVALID_REPEAT_OPTIONS, HttpStatus.BAD_REQUEST, {
-          reason: "pattern must be a valid cron expression (5- or 6-field)"
-        });
-      }
-    }
+    if ("pattern" in repeat) assertValidCron(repeat, this.options.queueOptions);
     const job = await queue.upsertJobScheduler(schedulerId, repeat, jobTemplate);
     return job;
   }
@@ -685,6 +701,9 @@ var FlowService = class {
    *
    * @param flow - Flow tree definition.
    * @returns The root `JobNode` containing the created job and its children.
+   *   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.
    */
   async add(flow) {
@@ -695,6 +714,7 @@ var FlowService = class {
    *
    * @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.
    */
   async addBulk(flows) {
@@ -807,20 +827,6 @@ var MetricsService = class {
 MetricsService = __decorateClass([
   Injectable()
 ], MetricsService);
-
-// src/server/utils/describe-error.ts
-function describeError(cause) {
-  try {
-    if (typeof cause === "object" && cause !== null && "message" in cause) {
-      if (typeof cause.message === "string") return cause.message;
-    }
-    return String(cause);
-  } catch {
-    return "unknown error";
-  }
-}
-
-// src/server/services/worker-registry.service.ts
 var _entries;
 var WorkerRegistry = class {
   constructor(connection, options) {
@@ -1207,6 +1213,7 @@ var WORKER_EVENT_LISTENERS_METADATA_KEY = /* @__PURE__ */ Symbol("bymax_queue:wo
 var QUEUE_EVENT_LISTENERS_METADATA_KEY = /* @__PURE__ */ Symbol("bymax_queue:queue_event_listeners");
 
 // src/server/services/processor-discovery.service.ts
+var EVENT_HANDLER_FAILED = "queue.event_handler_failed";
 var ProcessorDiscoveryService = class {
   constructor(discovery, workers, events) {
     this.discovery = discovery;
@@ -1301,7 +1308,14 @@ var ProcessorDiscoveryService = class {
     for (const { eventName, methodKey } of workerListeners) {
       const method = instance[methodKey];
       if (typeof method === "function") {
-        workerEmitter.on(eventName, method.bind(instance));
+        workerEmitter.on(
+          eventName,
+          this.guardListener(instance, method, {
+            decorator: "@OnWorkerEvent",
+            eventName,
+            methodKey
+          })
+        );
       }
     }
     const queueListeners = Reflect.getOwnMetadata(QUEUE_EVENT_LISTENERS_METADATA_KEY, ctor) ?? [];
@@ -1311,11 +1325,46 @@ var ProcessorDiscoveryService = class {
       for (const { eventName, methodKey } of queueListeners) {
         const method = instance[methodKey];
         if (typeof method === "function") {
-          qeEmitter.on(eventName, method.bind(instance));
+          qeEmitter.on(
+            eventName,
+            this.guardListener(instance, method, {
+              decorator: "@OnQueueEvent",
+              eventName,
+              methodKey
+            })
+          );
         }
       }
     }
   }
+  /**
+   * Bind an event listener so a failing handler is reported instead of escaping.
+   *
+   * An `EventEmitter` neither awaits a listener nor catches its throw: a rejected promise becomes
+   * an `unhandledRejection`, which ends the process by default, and BullMQ re-emits a synchronous
+   * throw as `error`. A failing handler is the consumer's defect, never a reason to
+   * stop the application, but it must still be visible, so the failure is logged with the handler
+   * and a stable code and the process carries on.
+   *
+   * @param instance - The provider the handler belongs to (its `this`).
+   * @param method - The handler method.
+   * @param origin - Which decorator, event and method name the listener comes from.
+   * @returns The listener to register on the emitter.
+   */
+  guardListener(instance, method, origin) {
+    const report = (cause) => {
+      this.logger.error(
+        `${origin.decorator}("${origin.eventName}") handler ${instance.constructor.name}.${String(origin.methodKey)} failed (${EVENT_HANDLER_FAILED}): ${describeError(cause)}`
+      );
+    };
+    return (...args) => {
+      try {
+        void Promise.resolve(method.apply(instance, args)).catch(report);
+      } catch (cause) {
+        report(cause);
+      }
+    };
+  }
 };
 ProcessorDiscoveryService = __decorateClass([
   Injectable(),
@@ -1323,6 +1372,8 @@ ProcessorDiscoveryService = __decorateClass([
   __decorateParam(1, Inject(WorkerRegistry)),
   __decorateParam(2, Inject(QueueEventsRegistry))
 ], ProcessorDiscoveryService);
+var DrainTimeoutError = class extends Error {
+};
 var QueueLifecycle = class {
   constructor(workers, events, queues, flow, connection, resolved) {
     this.workers = workers;
@@ -1368,10 +1419,10 @@ var QueueLifecycle = class {
     for (const [name, worker] of this.workers.getAll()) {
       try {
         await this.closeWorkerWithTimeout(worker, drainTimeoutMs);
-      } catch {
+      } catch (cause) {
         forced++;
         this.logger.warn(
-          `Worker "${name}" exceeded the ${String(drainTimeoutMs)}ms drain budget \u2014 forcing close (${QUEUE_ERROR_CODES.SHUTDOWN_TIMEOUT_EXCEEDED}); the in-flight job becomes stalled and is retried`
+          cause instanceof DrainTimeoutError ? `Worker "${name}" exceeded the ${String(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`
         );
         void worker.close(true).catch(() => void 0);
       }
@@ -1395,7 +1446,7 @@ var QueueLifecycle = class {
         closed,
         new Promise((_resolve, reject) => {
           timer = setTimeout(() => {
-            reject(new Error("drain timeout"));
+            reject(new DrainTimeoutError());
           }, timeoutMs);
         })
       ]);
@@ -1434,8 +1485,12 @@ var QueueLifecycle = class {
    */
   async drainQueuesIfRequested() {
     if (!this.resolved.shutdown.drainOnShutdown) return;
-    for (const [, queue] of this.queues.getCachedQueues()) {
-      await queue.drain().catch(() => void 0);
+    for (const [name, queue] of this.queues.getCachedQueues()) {
+      await queue.drain().catch((cause) => {
+        this.logger.warn(
+          `Queue "${name}" could not be drained on shutdown (drainOnShutdown): ${describeError(cause)}; its waiting jobs remain`
+        );
+      });
     }
   }
   /** Close the flow producer (idempotent), swallowing any failure. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-queue",
-  "version": "1.2.8",
+  "version": "1.2.10",
   "description": "NestJS dynamic module wrapping BullMQ — typed jobs, flows, job schedulers, deduplication, OpenTelemetry, graceful shutdown",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -55,6 +55,7 @@
   },
   "scripts": {
     "build": "pnpm clean && tsup",
+    "check:api": "node scripts/check-api-surface.mjs",
     "check:exports": "attw --pack .",
     "check:mutants": "node scripts/check-mutation-directives.mjs",
     "check:published": "node scripts/check-published-surface.mjs",