@bymax-one/nest-queue 1.2.9 → 1.2.11

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;
@@ -163,7 +163,6 @@ function applyDefaults(opts) {
   Object.defineProperty(base, "connection", {
     get: () => connection,
     enumerable: false,
-    // Stryker disable next-line BooleanLiteral: equivalent HERE — this object is `Object.freeze`d on the way out, and freezing makes every property non-configurable regardless. The flag stays because it states the guarantee at the point the accessor is defined, and because the sibling packages that withhold secrets the same way are NOT frozen, where it is load-bearing
     configurable: false
   });
   return Object.freeze(base);
@@ -200,21 +199,11 @@ function duplicateConnection(client) {
 var _client, _options;
 var ConnectionResolver = class {
   constructor(options) {
-    /**
-     * The resolved Redis client.
-     *
-     * An ECMAScript private field rather than a TypeScript `private` one, which
-     * is erased at runtime: an ioredis instance carries `options.password` as a
-     * plain field, so leaving this enumerable would let anything that serializes
-     * a service holding this resolver walk into the credentials.
-     */
     __privateAdd(this, _client);
-    /** The consumer's module options, which carry the Redis credentials. */
     __privateAdd(this, _options);
     __publicField(this, "mode");
     __privateSet(this, _options, options);
   }
-  /** Resolve and validate the connection. Call once during module bootstrap. */
   async init() {
     const cfg = __privateGet(this, _options).connection;
     if ("client" in cfg) {
@@ -227,18 +216,9 @@ var ConnectionResolver = class {
       __privateGet(this, _options).connectionReadyTimeoutMs ?? DEFAULT_CONNECTION_READY_TIMEOUT_MS
     );
   }
-  /**
-   * Merge the consumer's options with the owned-connection policy
-   * (`lazyConnect: false`, so the client connects eagerly and `init` can wait
-   * for `ready`) and narrow the result to the shape ioredis 6's constructor
-   * accepts. The runtime object is unchanged — the cast only drops the
-   * `undefined` that `RedisOptions.replyMapping` carries and the constructor
-   * rejects.
-   */
   ownedOptions(options) {
     return { ...options ?? {}, lazyConnect: false };
   }
-  /** The resolved Queue-role client. */
   getClient() {
     if (!__privateGet(this, _client)) {
       throw new QueueException(
@@ -251,7 +231,6 @@ var ConnectionResolver = class {
     }
     return __privateGet(this, _client);
   }
-  /** The resolved connection mode. */
   getMode() {
     if (!this.mode) {
       throw new QueueException(
@@ -264,11 +243,9 @@ var ConnectionResolver = class {
     }
     return this.mode;
   }
-  /** Whether the library owns (and must close) the connection. */
   isOwned() {
     return this.mode === "mode-b-owned";
   }
-  /** Close the library-owned connection on shutdown; never touch a BYO client. */
   async teardown() {
     if (this.isOwned() && __privateGet(this, _client)) {
       const client = __privateGet(this, _client);
@@ -277,7 +254,6 @@ var ConnectionResolver = class {
       });
     }
   }
-  /** Validate and adopt a bring-your-own client for the Queue role. */
   initModeA(client) {
     this.mode = "mode-a-byo";
     __privateSet(this, _client, client);
@@ -295,7 +271,6 @@ var ConnectionResolver = class {
       probe.disconnect();
     }
   }
-  /** Resolve when the owned client reaches `ready`, or reject on timeout/error. */
   async waitReady(timeoutMs) {
     const client = this.getClient();
     if (client.status === "ready") return;
@@ -387,8 +362,15 @@ function attachDefaultErrorListener(emitter, logger, kind, queueName) {
 
 // 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 {
@@ -400,14 +382,6 @@ var QueueService = class {
   }
   connection;
   options;
-  /**
-   * Return the cached `Queue` for `queueName`, or create one with the module
-   * defaults applied. Subsequent calls with the same name return the same
-   * instance.
-   *
-   * @param queueName - Unique queue name (used as the Redis key prefix).
-   * @param overrides - Optional per-queue option overrides.
-   */
   getOrCreateQueue(queueName, overrides) {
     const existing = __privateGet(this, _queues).get(queueName);
     if (existing) return existing;
@@ -423,70 +397,13 @@ var QueueService = class {
     __privateGet(this, _queues).set(queueName, queue);
     return queue;
   }
-  /** Resolve the raw cached queue (default generics) for internal delegation. */
   queueFor(queueName) {
     return this.getOrCreateQueue(queueName);
   }
-  /**
-   * 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
-   * idempotent: use an idempotency key on writes, prefer upserts over inserts, or
-   * keep an "already-processed" marker keyed by `job.id`.
-   *
-   * `options` surfaces BullMQ natives directly — including `jobId` (idempotent
-   * insert: a second add with the same id is a no-op while the first exists) and
-   * `deduplication` (windowed deduplication). The library writes no deduplication
-   * code; BullMQ owns the behavior. The deduplication key is independent of
-   * `jobId`, so both can be set together or apart. Both collapse duplicate
-   * **producers** and do not change the at-least-once guarantee on the
-   * **consumer** side.
-   *
-   * The deduplication `id` is a shared key across the queue, so a multi-tenant
-   * producer MUST scope it by tenant: keyed on the value alone
-   * (`` `reindex:${term}` ``), tenant A enqueuing a term suppresses tenant B's job
-   * for the same term.
-   *
-   * Scoping alone is not enough. Two variable fields joined by a delimiter that
-   * either may contain do not produce a unique key: with `` `${tenantId}:${term}` ``,
-   * the pairs `('a', 'b:c')` and `('a:b', 'c')` both yield `a:b:c`. Percent-encode
-   * every variable field so the delimiter cannot appear inside one:
-   * `` `${encodeURIComponent(tenantId)}:${encodeURIComponent(term)}` ``.
-   *
-   * Deduplication modes (`deduplication: { id, ttl?, extend?, replace?, keepLastIfActive? }`):
-   *  - Simple `{ id }` — collapse duplicates until the in-flight job completes or fails.
-   *  - Throttle `{ id, ttl }` — ignore duplicates for `ttl` milliseconds.
-   *  - Debounce `{ id, ttl, extend: true, replace: true }` — keep only the latest
-   *    data; each duplicate resets the TTL.
-   *  - keep-last-if-active `{ id, keepLastIfActive: true }` — while a job is active,
-   *    store the latest data and run a single follow-up when it finishes.
-   *
-   * @param queueName - Target queue (created lazily if absent).
-   * @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.
-   * @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)}`
-   *   await queueService.enqueue('search', 'reindex', { term }, {
-   *     deduplication: { id: dedupId, ttl: 5_000 },
-   *   })
-   */
   async enqueue(queueName, jobName, data, options) {
     const job = await this.queueFor(queueName).add(jobName, data, options);
     return job;
   }
-  /**
-   * Enqueue multiple jobs in a single Redis roundtrip. The batch is bounded by
-   * {@link MAX_BULK_SIZE} to guard against a self-inflicted memory spike; any
-   * failure is wrapped in a `QueueException`. Delivery is at-least-once, so every
-   * job's handler must be idempotent (see {@link QueueService.enqueue}).
-   *
-   * @param queueName - Target queue.
-   * @param jobs - Job descriptors (length must not exceed the bulk size cap).
-   */
   async enqueueBulk(queueName, jobs) {
     if (jobs.length > MAX_BULK_SIZE) {
       throw new QueueException(
@@ -518,33 +435,14 @@ var QueueService = class {
       );
     }
   }
-  /**
-   * Fetch a job by id. Returns `null` when the job does not exist.
-   *
-   * @param queueName - Target queue.
-   * @param jobId - The job identifier.
-   */
   async getJob(queueName, jobId) {
     const job = await this.queueFor(queueName).getJob(jobId);
     return job ?? null;
   }
-  /**
-   * Fetch jobs in a given status with pagination.
-   *
-   * @param queueName - Target queue.
-   * @param status - Status filter.
-   * @param start - Starting index (inclusive). Default: 0.
-   * @param end - Ending index (inclusive). Default: 50.
-   */
   async getJobs(queueName, status, start = 0, end = 50) {
     const jobs = await this.queueFor(queueName).getJobs([status], start, end);
     return jobs;
   }
-  /**
-   * Return an uncached snapshot of job counts grouped by status.
-   *
-   * @param queueName - Target queue.
-   */
   async getMetrics(queueName) {
     const counts = await this.queueFor(queueName).getJobCounts(
       "waiting",
@@ -559,24 +457,6 @@ var QueueService = class {
       collectedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
   }
-  /**
-   * Create or update a Job Scheduler — the current BullMQ recurring-jobs API.
-   * Idempotent by `schedulerId`: BullMQ performs an atomic `override: true`
-   * upsert, so re-registering on every boot updates the schedule in place and
-   * 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).
-   *
-   * @param queueName - Target queue.
-   * @param schedulerId - Stable, unique scheduler identifier (the upsert key).
-   * @param repeat - Cron `pattern` OR `every` (ms), plus optional tz/limit/start/end.
-   * @param template - Optional job template; `name` defaults to `schedulerId`, `data` to `{}`.
-   * @returns The first scheduled (delayed) job, or `undefined`.
-   * @throws {QueueException} `INVALID_REPEAT_OPTIONS` (400) for an invalid schedule.
-   */
   async upsertJobScheduler(queueName, schedulerId, repeat, template) {
     validateJobSchedulerOptions(repeat);
     const queue = this.queueFor(queueName);
@@ -585,76 +465,28 @@ 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;
   }
-  /**
-   * Remove a Job Scheduler by id.
-   *
-   * @param queueName - Target queue.
-   * @param schedulerId - The scheduler identifier to remove.
-   * @returns `true` when a scheduler was removed, `false` otherwise.
-   */
   async removeJobScheduler(queueName, schedulerId) {
     return this.queueFor(queueName).removeJobScheduler(schedulerId);
   }
-  /**
-   * List the Job Schedulers registered on a queue, for inspection or health checks.
-   *
-   * @param queueName - Target queue.
-   * @param start - Page start index (inclusive). Default: 0.
-   * @param end - Page end index (inclusive). Default: 50.
-   * @param asc - Sort ascending by next run time. Default: true.
-   * @returns The registered schedulers in the requested page.
-   */
   async getJobSchedulers(queueName, start = 0, end = 50, asc = true) {
     return this.queueFor(queueName).getJobSchedulers(start, end, asc);
   }
-  /** Pause a queue, halting the processing of new jobs. */
   async pauseQueue(queueName) {
     await this.queueFor(queueName).pause();
   }
-  /** Resume a previously paused queue. */
   async resumeQueue(queueName) {
     await this.queueFor(queueName).resume();
   }
-  /**
-   * Remove up to `limit` jobs older than `gracePeriodMs` in a given status. The
-   * argument order mirrors BullMQ's `Queue.clean(grace, limit, type?)` exactly;
-   * `limit` is required and `0` means no limit. Returns the removed job ids.
-   *
-   * @param queueName - Target queue.
-   * @param gracePeriodMs - Keep jobs younger than this many milliseconds.
-   * @param limit - Maximum number of jobs to remove (`0` = no limit).
-   * @param status - Status of jobs to clean.
-   */
   async cleanQueue(queueName, gracePeriodMs, limit, status) {
     return this.queueFor(queueName).clean(gracePeriodMs, limit, status);
   }
-  /** Return a read-only view of the cached queues. */
   getCachedQueues() {
     return __privateGet(this, _queues);
   }
-  /**
-   * Close every cached queue (swallowing per-queue errors) and clear the cache.
-   *
-   * Deliberately NOT named `onModuleDestroy`: NestJS invokes lifecycle hooks by
-   * method name, so a hook here would run on Nest's own schedule, concurrently
-   * with — and possibly before — the bounded drain in `QueueLifecycle`. Closing a
-   * queue while its worker is still draining is exactly what the ordered sequence
-   * exists to prevent. `QueueLifecycle` is the only caller.
-   */
   async closeAll() {
     for (const queue of __privateGet(this, _queues).values()) {
       await queue.close().catch(() => void 0);
@@ -675,73 +507,26 @@ var FlowService = class {
     if (enabled) {
       this.producer = new FlowProducer({
         connection: connection.getClient(),
-        // Match the producer Queue's key prefix so flow jobs land in the same
-        // keyspace the workers poll; a non-default prefix breaks flows otherwise.
         prefix,
         ...telemetry ? { telemetry } : {}
       });
       attachDefaultErrorListener(this.producer, this.logger, "FlowProducer", "*");
     }
   }
-  /**
-   * Add a flow tree (a parent with its descendant children). The root job
-   * becomes processable only after every descendant has completed.
-   *
-   * By BullMQ default a failed (retry-exhausted) child does NOT fail its parent:
-   * the parent stays in the `waiting-children` state until the child eventually
-   * completes. To make a child's failure propagate upward and fail its parent,
-   * set `failParentOnFailure: true` on that child (it cascades when ancestors
-   * also set it). To let a parent proceed despite a failed child, set
-   * `ignoreDependencyOnFailure: true` on that child. Bound each child's
-   * `attempts` so an unrecoverable child cannot leave the parent waiting forever.
-   *
-   * @param flow - Flow tree definition.
-   * @returns The root `JobNode` containing the created job and its children.
-   * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled.
-   */
   async add(flow) {
     return this.requireProducer().add(flow);
   }
-  /**
-   * Add multiple flow trees in a single Redis roundtrip.
-   *
-   * @param flows - Flow tree definitions.
-   * @returns The root `JobNode` for each flow, in input order.
-   * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled.
-   */
   async addBulk(flows) {
     return this.requireProducer().addBulk([...flows]);
   }
-  /**
-   * Escape hatch returning the underlying `FlowProducer` for advanced use cases.
-   * Prefer {@link FlowService.add} / {@link FlowService.addBulk} when possible.
-   *
-   * @returns The underlying BullMQ `FlowProducer`.
-   * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled.
-   */
   getProducer() {
     return this.requireProducer();
   }
-  /**
-   * Close the producer when active; a no-op when inactive. A failed `close()` is
-   * swallowed so it never aborts the shutdown sequence.
-   *
-   * Deliberately NOT named `onModuleDestroy`: NestJS invokes lifecycle hooks by
-   * method name, so a hook here would run in addition to the call the ordered
-   * sequence already makes, closing the producer twice. `QueueLifecycle` is the
-   * only caller.
-   */
   async close() {
     if (this.producer) {
       await this.producer.close().catch(() => void 0);
     }
   }
-  /**
-   * Return the active producer or throw when flows are disabled. The producer is
-   * present if and only if flows were enabled at construction time.
-   *
-   * @throws {QueueException} `FLOW_DISABLED` (503) when no producer exists.
-   */
   requireProducer() {
     if (!this.producer) {
       throw new QueueException(QUEUE_ERROR_CODES.FLOW_DISABLED, HttpStatus.SERVICE_UNAVAILABLE);
@@ -762,14 +547,6 @@ var MetricsService = class {
   enabled;
   ttlMs;
   cache = /* @__PURE__ */ new Map();
-  /**
-   * Return cached metrics for `queueName`, or fetch fresh (and cache them) on a
-   * miss or after expiry.
-   *
-   * @param queueName - Target queue.
-   * @returns The current metrics snapshot.
-   * @throws {QueueException} `METRICS_DISABLED` (503) when metrics are disabled.
-   */
   async get(queueName) {
     this.ensureEnabled();
     const entry = this.cache.get(queueName);
@@ -780,23 +557,11 @@ var MetricsService = class {
     this.cache.set(queueName, { metrics, expiresAt: Date.now() + this.ttlMs });
     return metrics;
   }
-  /**
-   * Return a metrics snapshot for every queue currently cached in `QueueService`.
-   *
-   * @returns Metrics for all known queues.
-   * @throws {QueueException} `METRICS_DISABLED` (503) when metrics are disabled.
-   */
   async getAll() {
     this.ensureEnabled();
     const names = Array.from(this.queueService.getCachedQueues().keys());
     return Promise.all(names.map((name) => this.get(name)));
   }
-  /**
-   * Invalidate the cache for `queueName`, or the whole cache when omitted.
-   *
-   * @param queueName - The queue entry to drop; omit to clear everything.
-   * @throws {QueueException} `METRICS_DISABLED` (503) when metrics are disabled.
-   */
   invalidate(queueName) {
     this.ensureEnabled();
     if (queueName === void 0) {
@@ -805,11 +570,6 @@ var MetricsService = class {
     }
     this.cache.delete(queueName);
   }
-  /**
-   * Guard every operation behind the opt-in flag.
-   *
-   * @throws {QueueException} `METRICS_DISABLED` (503) when metrics are disabled.
-   */
   ensureEnabled() {
     if (!this.enabled) {
       throw new QueueException(QUEUE_ERROR_CODES.METRICS_DISABLED, HttpStatus.SERVICE_UNAVAILABLE);
@@ -829,19 +589,6 @@ var WorkerRegistry = class {
   }
   connection;
   options;
-  /**
-   * Register an in-process worker with a handler function. The BullMQ `Worker`
-   * constructor is synchronous — no Redis handshake is performed at registration
-   * time. The duplicated connection is disconnected immediately if construction
-   * fails, preventing a Redis connection leak.
-   *
-   * @param config - Queue name, handler, and optional worker options.
-   * @returns The created BullMQ `Worker` instance.
-   * @throws {QueueException} `DUPLICATE_PROCESSOR` when a worker for
-   *   `queueName` already exists.
-   * @throws {QueueException} `WORKER_REGISTRATION_FAILED` when options are
-   *   invalid or the BullMQ `Worker` constructor throws.
-   */
   register(config) {
     const { queueName, handler, options } = config;
     this.guardDuplicate(queueName);
@@ -866,21 +613,6 @@ var WorkerRegistry = class {
     __privateGet(this, _entries).set(queueName, { worker, connection: conn });
     return worker;
   }
-  /**
-   * Register a sandboxed (file-based, out-of-process) worker. The processor
-   * file must be an absolute path or a `file:` URL pointing to a compiled
-   * `.js`/`.cjs`/`.mjs` artifact. NestJS DI is **not** available inside the
-   * processor. The BullMQ `Worker` constructor is synchronous.
-   *
-   * @param config - Queue name, processor file path/URL, and optional options.
-   * @returns The created BullMQ `Worker` instance.
-   * @throws {QueueException} `WORKER_REGISTRATION_FAILED` when `processorFile`
-   *   is a relative path, has a disallowed extension, or uses a non-`file:` URL protocol.
-   * @throws {QueueException} `DUPLICATE_PROCESSOR` when a worker for
-   *   `queueName` already exists.
-   * @throws {QueueException} `WORKER_REGISTRATION_FAILED` when options are
-   *   invalid or the BullMQ `Worker` constructor throws.
-   */
   registerSandboxed(config) {
     const { queueName, processorFile, options } = config;
     this.validateProcessorFile(processorFile);
@@ -909,13 +641,6 @@ var WorkerRegistry = class {
     __privateGet(this, _entries).set(queueName, { worker, connection: conn });
     return worker;
   }
-  /**
-   * Stop and remove the worker for the given queue, releasing the duplicated
-   * connection the library opened for it. If no worker exists for `queueName`
-   * this is a no-op.
-   *
-   * @param queueName - The queue whose worker should be removed.
-   */
   async unregister(queueName) {
     const entry = __privateGet(this, _entries).get(queueName);
     if (!entry) return;
@@ -923,44 +648,19 @@ var WorkerRegistry = class {
     await this.closeConnection(entry.connection);
     __privateGet(this, _entries).delete(queueName);
   }
-  /**
-   * Returns the queue names of all currently registered workers.
-   *
-   * @returns An immutable array of queue names.
-   */
   list() {
     return Array.from(__privateGet(this, _entries).keys());
   }
-  /**
-   * Returns a read-only view of the registered workers keyed by queue name.
-   * Intended for the shutdown orchestrator only.
-   *
-   * @returns A read-only map of queue name to worker.
-   */
   getAll() {
     return new Map(
       Array.from(__privateGet(this, _entries), ([name, entry]) => [name, entry.worker])
     );
   }
-  /**
-   * Returns a read-only view of the duplicated connections the library opened
-   * for its workers, keyed by queue name. Intended for the shutdown orchestrator
-   * so it can close exactly the connections the library created (Mode A never
-   * exposes the consumer's shared client here).
-   *
-   * @returns A read-only map of queue name to duplicated connection.
-   */
   getConnections() {
     return new Map(
       Array.from(__privateGet(this, _entries), ([name, entry]) => [name, entry.connection])
     );
   }
-  /**
-   * Gracefully quit a duplicated connection, falling back to a hard disconnect
-   * if the quit handshake fails so a socket is never leaked.
-   *
-   * @param connection - The duplicated connection to release.
-   */
   async closeConnection(connection) {
     try {
       await connection.quit();
@@ -968,12 +668,6 @@ var WorkerRegistry = class {
       connection.disconnect();
     }
   }
-  /**
-   * Guard against registering two workers for the same queue.
-   *
-   * @param queueName - Queue name to check.
-   * @throws {QueueException} `DUPLICATE_PROCESSOR` if the queue is already registered.
-   */
   guardDuplicate(queueName) {
     if (__privateGet(this, _entries).has(queueName)) {
       throw new QueueException(
@@ -983,14 +677,6 @@ var WorkerRegistry = class {
       );
     }
   }
-  /**
-   * Validate tunable options before constructing a Worker.
-   * Enforces `concurrency` in `[1, MAX_WORKER_CONCURRENCY]` and
-   * `limiter.max`/`limiter.duration` `>= 1`.
-   *
-   * @param opts - The caller-supplied options (may be undefined).
-   * @throws {QueueException} `WORKER_REGISTRATION_FAILED` when values are out of range.
-   */
   validateOptions(opts) {
     if (opts?.concurrency !== void 0) {
       if (opts.concurrency < 1) {
@@ -1037,15 +723,6 @@ var WorkerRegistry = class {
       }
     }
   }
-  /**
-   * Validate that `processorFile` is a safe, reachable artifact path. Accepts
-   * absolute paths with `.js`/`.cjs`/`.mjs` extensions and `file:` URLs. Rejects
-   * relative paths, non-JS extensions, and non-`file:` URL protocols to prevent
-   * path-traversal and arbitrary-file-execution attacks.
-   *
-   * @param processorFile - The path or URL supplied by the caller.
-   * @throws {QueueException} `WORKER_REGISTRATION_FAILED` when validation fails.
-   */
   validateProcessorFile(processorFile) {
     if (processorFile instanceof URL) {
       if (processorFile.protocol !== "file:") {
@@ -1071,13 +748,6 @@ var WorkerRegistry = class {
     }
     this.assertProcessorExtension(processorFile);
   }
-  /**
-   * Reject a processor path whose extension is not an executable JS module,
-   * the last line of defense against loading an arbitrary file as a worker.
-   *
-   * @param filePath - The filesystem path (or file: URL pathname) to check.
-   * @throws {QueueException} `WORKER_REGISTRATION_FAILED` for a disallowed extension.
-   */
   assertProcessorExtension(filePath) {
     const allowedExtensions = /* @__PURE__ */ new Set([".js", ".cjs", ".mjs"]);
     if (!allowedExtensions.has(extname(filePath))) {
@@ -1090,23 +760,11 @@ var WorkerRegistry = class {
       );
     }
   }
-  /**
-   * Build a BullMQ `WorkerOptions` object from the library's `WorkerOptions`
-   * shape. Only forwards optional fields that are explicitly set to preserve
-   * `exactOptionalPropertyTypes` correctness. Accepts the pre-created duplicated
-   * connection so callers can close it on construction failure.
-   *
-   * @param opts - Library-level worker options.
-   * @param conn - Pre-created duplicated Redis connection.
-   * @returns A BullMQ-compatible options object.
-   */
   buildBullOptions(opts, conn) {
     const result = {
       connection: conn,
       concurrency: opts?.concurrency ?? DEFAULT_WORKER_CONCURRENCY,
       autorun: opts?.autorun ?? true,
-      // Match the producer Queue's key prefix so the worker polls the same
-      // keyspace; without this a non-default prefix leaves jobs unconsumed.
       prefix: this.options.prefix
     };
     if (opts?.limiter !== void 0) result.limiter = opts.limiter;
@@ -1133,14 +791,6 @@ var QueueEventsRegistry = class {
   }
   connection;
   options;
-  /**
-   * Returns the cached `QueueEvents` for `queueName`, creating one on first
-   * call. Subsequent calls for the same name return the same instance without
-   * opening a second Redis connection.
-   *
-   * @param queueName - The BullMQ queue to observe.
-   * @returns The `QueueEvents` instance for the queue.
-   */
   getOrCreate(queueName) {
     const existing = __privateGet(this, _events).get(queueName);
     if (existing) return existing;
@@ -1157,35 +807,12 @@ var QueueEventsRegistry = class {
     __privateGet(this, _connections).set(queueName, conn);
     return qe;
   }
-  /**
-   * Returns the queue names for which a `QueueEvents` connection is open.
-   *
-   * @returns An immutable array of queue names.
-   */
   list() {
     return Array.from(__privateGet(this, _events).keys());
   }
-  /**
-   * Returns the live `QueueEvents` map. Intended for the shutdown orchestrator.
-   *
-   * @returns A read-only view of the internal map.
-   */
   getAll() {
     return __privateGet(this, _events);
   }
-  /**
-   * Returns a read-only view of the duplicated connections the library opened
-   * for its `QueueEvents`, keyed by queue name. Intended for the shutdown
-   * orchestrator so it can close exactly the connections the library created
-   * (Mode A never exposes the consumer's shared client here).
-   *
-   * Returns a copy. `ReadonlyMap` is a compile-time claim only — handing back the
-   * live registry lets any consumer cast it away and delete a connection the
-   * shutdown sequence is about to close. The allocation costs nothing on a path
-   * that runs once per shutdown.
-   *
-   * @returns A read-only snapshot of queue name to duplicated connection.
-   */
   getConnections() {
     return new Map(__privateGet(this, _connections));
   }
@@ -1205,6 +832,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;
@@ -1216,10 +844,6 @@ var ProcessorDiscoveryService = class {
   events;
   logger = new Logger(ProcessorDiscoveryService.name);
   registeredQueues = /* @__PURE__ */ new Set();
-  /**
-   * Entry point called by NestJS after the module is fully initialized.
-   * Discovers all `@Processor`-annotated providers and wires them.
-   */
   onModuleInit() {
     const providers = this.discovery.getProviders();
     for (const wrapper of providers) {
@@ -1231,15 +855,6 @@ var ProcessorDiscoveryService = class {
       this.wireProcessor(instance, processorMeta);
     }
   }
-  /**
-   * Build a dispatcher function that routes `job.name` to the correct handler.
-   * Named handlers take priority; a catch-all (`@Process()`) handles everything
-   * else. Throws if no matching handler is found at job-processing time.
-   *
-   * @param instance - The provider instance whose methods serve as handlers.
-   * @param handlers - Accumulated `@Process` metadata entries for the class.
-   * @returns A dispatcher `(job: Job) => Promise<unknown>`.
-   */
   buildDispatcher(instance, handlers) {
     const namedHandlers = /* @__PURE__ */ new Map();
     let catchAll;
@@ -1264,13 +879,6 @@ var ProcessorDiscoveryService = class {
       );
     };
   }
-  /**
-   * Wire a single discovered processor class: validate uniqueness, register a
-   * Worker, bind worker-local and queue-global event listeners.
-   *
-   * @param instance - The resolved provider instance.
-   * @param processorMeta - Metadata written by `@Processor`.
-   */
   wireProcessor(instance, processorMeta) {
     const { queueName, workerOptions, _warnedNoConcurrency } = processorMeta;
     const ctor = instance.constructor;
@@ -1299,7 +907,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) ?? [];
@@ -1309,11 +924,32 @@ 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
+            })
+          );
         }
       }
     }
   }
+  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(),
@@ -1321,6 +957,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;
@@ -1337,53 +975,39 @@ var QueueLifecycle = class {
   connection;
   resolved;
   logger = new Logger(QueueLifecycle.name);
-  /**
-   * Run the ordered shutdown sequence. Called by NestJS when the application
-   * context closes (e.g. on `SIGTERM` with shutdown hooks enabled).
-   */
+  startedAt;
+  forcedWorkers = 0;
   async onModuleDestroy() {
-    const start = Date.now();
-    const forced = await this.closeWorkers();
+    this.startedAt = Date.now();
+    this.forcedWorkers = await this.closeWorkers();
     await this.closeQueueEvents();
     await this.closeDuplicatedConnections();
+  }
+  async onApplicationShutdown() {
     await this.drainQueuesIfRequested();
     await this.closeFlowProducer();
     await this.closeQueues();
     await this.teardownConnection();
     this.logger.log(
-      `Queue shutdown complete in ${String(Date.now() - start)}ms (forced ${String(forced)} worker(s))`
+      `Queue shutdown complete in ${String(Date.now() - (this.startedAt ?? Date.now()))}ms (forced ${String(this.forcedWorkers)} worker(s))`
     );
   }
-  /**
-   * Close every worker with a bounded drain, force-closing any that exceed the
-   * budget. Returns the number of workers that had to be force-closed.
-   *
-   * @returns The count of force-closed workers.
-   */
   async closeWorkers() {
     let forced = 0;
     const drainTimeoutMs = this.resolved.shutdown.drainTimeoutMs;
     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);
       }
     }
     return forced;
   }
-  /**
-   * Race a graceful `worker.close()` against a timer. `worker.close()` already
-   * drains active jobs and takes no timeout argument, so the timer is the only
-   * way to bound the wait. Rejects with a timeout error when the budget elapses.
-   *
-   * @param worker - The worker to close.
-   * @param timeoutMs - The drain budget in milliseconds.
-   */
   async closeWorkerWithTimeout(worker, timeoutMs) {
     let timer;
     const closed = worker.close();
@@ -1393,7 +1017,7 @@ var QueueLifecycle = class {
         closed,
         new Promise((_resolve, reject) => {
           timer = setTimeout(() => {
-            reject(new Error("drain timeout"));
+            reject(new DrainTimeoutError());
           }, timeoutMs);
         })
       ]);
@@ -1401,18 +1025,11 @@ var QueueLifecycle = class {
       clearTimeout(timer);
     }
   }
-  /** Close every cached `QueueEvents`, swallowing individual failures. */
   async closeQueueEvents() {
     for (const [, queueEvents] of this.events.getAll()) {
       await queueEvents.close().catch(() => void 0);
     }
   }
-  /**
-   * Close the duplicated worker/queue-events connections the library opened.
-   * BullMQ treats a passed-in client as shared and never closes it, so the
-   * library must release these explicitly. In Mode A the consumer's shared
-   * client is never among them.
-   */
   async closeDuplicatedConnections() {
     const connections = [
       ...this.workers.getConnections().values(),
@@ -1426,28 +1043,22 @@ var QueueLifecycle = class {
       }
     }
   }
-  /**
-   * Drain every cached queue when `drainOnShutdown` is enabled (dev/test only).
-   * Removes waiting jobs and leaves delayed and active ones; off by default to stay production-safe.
-   */
   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. */
   async closeFlowProducer() {
     await this.flow.close().catch(() => void 0);
   }
-  /** Close every cached queue and clear the cache, swallowing individual failures. */
   async closeQueues() {
     await this.queues.closeAll().catch(() => void 0);
   }
-  /**
-   * Tear down the Queue-role connection. Mode B quits the library-owned client;
-   * Mode A is a no-op for the consumer's shared client.
-   */
   async teardownConnection() {
     await this.connection.teardown().catch(() => void 0);
   }
@@ -1464,24 +1075,12 @@ QueueLifecycle = __decorateClass([
 
 // src/server/bymax-queue.module.ts
 var { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } = (
-  // The `moduleName` shapes the generated option token's identifier — `BYMAX_QUEUE_MODULE_OPTIONS`,
-  // which the module spec asserts by value; emptying the name would degrade it to an opaque
-  // `CONFIGURABLE_MODULE_OPTIONS[<hash>]`, so the argument is a caught regression, not a free label.
   new ConfigurableModuleBuilder({ moduleName: "BymaxQueue" }).setClassMethodName("forRoot").setFactoryMethodName("createQueueOptions").setExtras({ isGlobal: true }, (definition, extras) => ({
     ...definition,
     global: extras.isGlobal
   })).build()
 );
 var BymaxQueueModule = class extends ConfigurableModuleClass {
-  /**
-   * Synchronous registration. Validates options, resolves defaults, and wires the
-   * connection resolver (initialized via async factory), the queue service, the
-   * worker registry, the queue-events registry, processor discovery, and the
-   * graceful-shutdown lifecycle.
-   *
-   * @param options - Static module options.
-   * @returns The configured dynamic module.
-   */
   static forRoot(options) {
     validateOptions(options);
     const resolved = applyDefaults(options);
@@ -1507,17 +1106,6 @@ var BymaxQueueModule = class extends ConfigurableModuleClass {
       exports: BymaxQueueModule.buildExports()
     };
   }
-  /**
-   * Asynchronous registration. Use when options depend on other modules
-   * (ConfigService, BymaxCacheModule, etc.). Mirrors the NestJS standard async
-   * dynamic-module pattern (`useFactory` | `useClass` | `useExisting` + `inject`)
-   * and registers the same provider graph and exports as {@link forRoot}, with
-   * `global` applied from the `isGlobal` extra. The resolved options and the
-   * initialized connection are derived from the async-resolved options at runtime.
-   *
-   * @param options - Asynchronous module options.
-   * @returns The configured dynamic module.
-   */
   static forRootAsync(options) {
     const base = super.forRootAsync(options);
     return {
@@ -1548,14 +1136,6 @@ var BymaxQueueModule = class extends ConfigurableModuleClass {
       exports: BymaxQueueModule.buildExports()
     };
   }
-  /**
-   * Providers shared verbatim by both registration paths: the options alias, the
-   * initialized connection resolver, the resolved client/mode tokens, and the
-   * singleton services. `BYMAX_QUEUE_RESOLVED_OPTIONS`, `FlowService`, and
-   * `MetricsService` are intentionally omitted — they differ per path.
-   *
-   * @returns The shared provider list.
-   */
   static buildCoreProviders() {
     return [
       { provide: BYMAX_QUEUE_OPTIONS, useExisting: MODULE_OPTIONS_TOKEN },
@@ -1585,11 +1165,6 @@ var BymaxQueueModule = class extends ConfigurableModuleClass {
       QueueLifecycle
     ];
   }
-  /**
-   * The public exports shared by both registration paths.
-   *
-   * @returns A fresh exports list (services and injection tokens).
-   */
   static buildExports() {
     return [
       QueueService,