@bymax-one/nest-queue 1.0.0

package/dist/server/index.mjs

@@ -0,0 +1,1500 @@
+import { Injectable, Inject, ConfigurableModuleBuilder, Module, Logger, HttpException, HttpStatus } from '@nestjs/common';
+import { DiscoveryService, DiscoveryModule } from '@nestjs/core';
+import { Redis } from 'ioredis';
+import { Worker, QueueEvents, Queue, FlowProducer } from 'bullmq';
+import { isAbsolute, extname } from 'path';
+import 'reflect-metadata';
+
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (decorator(result)) || result;
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/shared/constants/error-codes.ts
+var QUEUE_ERROR_CODES = {
+  CONNECTION_INVALID: "queue.connection_invalid",
+  CONNECTION_REQUIRES_NULL_RETRIES: "queue.connection_requires_null_retries",
+  CONNECTION_TIMEOUT: "queue.connection_timeout",
+  QUEUE_NOT_FOUND: "queue.queue_not_found",
+  JOB_NOT_FOUND: "queue.job_not_found",
+  INVALID_JOB_DATA: "queue.invalid_job_data",
+  INVALID_REPEAT_OPTIONS: "queue.invalid_repeat_options",
+  DUPLICATE_PROCESSOR: "queue.duplicate_processor",
+  FLOW_DISABLED: "queue.flow_disabled",
+  METRICS_DISABLED: "queue.metrics_disabled",
+  SHUTDOWN_TIMEOUT_EXCEEDED: "queue.shutdown_timeout_exceeded",
+  BULK_ENQUEUE_FAILED: "queue.bulk_enqueue_failed",
+  WORKER_REGISTRATION_FAILED: "queue.worker_registration_failed",
+  INVALID_OPTIONS: "queue.invalid_options"
+};
+
+// src/server/constants/error-codes.ts
+var QUEUE_ERROR_MESSAGES = {
+  [QUEUE_ERROR_CODES.CONNECTION_INVALID]: "Invalid Redis connection configuration",
+  [QUEUE_ERROR_CODES.CONNECTION_REQUIRES_NULL_RETRIES]: "Worker connection must have maxRetriesPerRequest=null",
+  [QUEUE_ERROR_CODES.CONNECTION_TIMEOUT]: "Redis connection timeout",
+  [QUEUE_ERROR_CODES.QUEUE_NOT_FOUND]: "Queue not found",
+  [QUEUE_ERROR_CODES.JOB_NOT_FOUND]: "Job not found",
+  [QUEUE_ERROR_CODES.INVALID_JOB_DATA]: "Invalid job data",
+  [QUEUE_ERROR_CODES.INVALID_REPEAT_OPTIONS]: "Invalid repeat options",
+  [QUEUE_ERROR_CODES.DUPLICATE_PROCESSOR]: "Multiple processor decorators target the same queue",
+  [QUEUE_ERROR_CODES.FLOW_DISABLED]: "Flow support is disabled",
+  [QUEUE_ERROR_CODES.METRICS_DISABLED]: "Metrics support is disabled",
+  [QUEUE_ERROR_CODES.SHUTDOWN_TIMEOUT_EXCEEDED]: "Shutdown timeout exceeded",
+  [QUEUE_ERROR_CODES.BULK_ENQUEUE_FAILED]: "Bulk enqueue failed",
+  [QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED]: "Failed to register worker",
+  [QUEUE_ERROR_CODES.INVALID_OPTIONS]: "Invalid module options"
+};
+
+// src/server/errors/queue-exception.ts
+var QueueException = class extends HttpException {
+  constructor(code, statusCode = HttpStatus.INTERNAL_SERVER_ERROR, details) {
+    super(
+      {
+        error: {
+          code,
+          message: QUEUE_ERROR_MESSAGES[code] ?? "Queue error",
+          details: details ?? null
+        }
+      },
+      statusCode
+    );
+  }
+};
+
+// src/server/config/validate-options.ts
+function invalid(reason) {
+  throw new QueueException(QUEUE_ERROR_CODES.INVALID_OPTIONS, 500, { reason });
+}
+function validateOptions(opts) {
+  const cfg = opts.connection;
+  if (cfg === null || typeof cfg !== "object") {
+    invalid("connection is required");
+  }
+  const hasClient = "client" in cfg;
+  const hasUrl = "url" in cfg;
+  const hasOptions = "options" in cfg;
+  if (!hasClient && !hasUrl && !hasOptions) {
+    invalid("connection must specify client | url | options");
+  }
+  if (hasClient && (hasUrl || hasOptions)) {
+    invalid("connection.client is mutually exclusive with url/options");
+  }
+  const drainTimeoutMs = opts.shutdown?.drainTimeoutMs;
+  if (drainTimeoutMs !== void 0 && drainTimeoutMs <= 0) {
+    invalid("shutdown.drainTimeoutMs must be > 0");
+  }
+  const cacheTtlMs = opts.metrics?.cacheTtlMs;
+  if (cacheTtlMs !== void 0 && cacheTtlMs < 0) {
+    invalid("metrics.cacheTtlMs must be >= 0");
+  }
+}
+
+// src/server/constants/default-options.ts
+var DEFAULT_WORKER_CONCURRENCY = 2;
+var MAX_WORKER_CONCURRENCY = 1e3;
+var DEFAULT_JOB_OPTIONS = {
+  attempts: 3,
+  backoff: { type: "exponential", delay: 2e3 },
+  removeOnComplete: { age: 24 * 3600, count: 1e3 },
+  removeOnFail: { age: 7 * 24 * 3600, count: 5e3 }
+};
+var DEFAULT_CONNECTION_READY_TIMEOUT_MS = 1e4;
+var DEFAULT_METRICS_CACHE_TTL_MS = 5e3;
+var DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS = 3e4;
+
+// src/server/config/resolved-options.ts
+function applyDefaults(opts) {
+  const base = {
+    connection: opts.connection,
+    defaultJobOptions: { ...DEFAULT_JOB_OPTIONS, ...opts.defaultJobOptions ?? {} },
+    prefix: opts.prefix ?? "bull",
+    queueOptions: opts.queueOptions ?? {},
+    flows: { enabled: opts.flows?.enabled ?? false },
+    metrics: {
+      enabled: opts.metrics?.enabled ?? false,
+      cacheTtlMs: opts.metrics?.cacheTtlMs ?? DEFAULT_METRICS_CACHE_TTL_MS
+    },
+    shutdown: {
+      drainTimeoutMs: opts.shutdown?.drainTimeoutMs ?? DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS,
+      drainOnShutdown: opts.shutdown?.drainOnShutdown ?? false
+    },
+    connectionReadyTimeoutMs: opts.connectionReadyTimeoutMs ?? DEFAULT_CONNECTION_READY_TIMEOUT_MS
+  };
+  if (opts.telemetry !== void 0) base.telemetry = opts.telemetry;
+  return Object.freeze(base);
+}
+
+// src/server/bymax-queue.constants.ts
+var BYMAX_QUEUE_OPTIONS = /* @__PURE__ */ Symbol("BYMAX_QUEUE_OPTIONS");
+var BYMAX_QUEUE_REDIS_CLIENT = /* @__PURE__ */ Symbol("BYMAX_QUEUE_REDIS_CLIENT");
+var BYMAX_QUEUE_CONNECTION_MODE = /* @__PURE__ */ Symbol("BYMAX_QUEUE_CONNECTION_MODE");
+var BYMAX_QUEUE_RESOLVED_OPTIONS = /* @__PURE__ */ Symbol("BYMAX_QUEUE_RESOLVED_OPTIONS");
+
+// src/server/utils/validate-connection.ts
+function assertBlockingConnection(client) {
+  const actualValue = client.options?.maxRetriesPerRequest;
+  if (actualValue !== null) {
+    throw new QueueException(QUEUE_ERROR_CODES.CONNECTION_REQUIRES_NULL_RETRIES, 500, {
+      actualValue: actualValue ?? null,
+      expectedValue: null
+    });
+  }
+}
+function isClientUsable(client) {
+  return client.status === "ready" || client.status === "connecting";
+}
+
+// src/server/utils/duplicate-connection.ts
+function duplicateConnection(client) {
+  return client.duplicate({ maxRetriesPerRequest: null });
+}
+
+// src/server/services/connection-resolver.service.ts
+var ConnectionResolver = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  client;
+  mode;
+  /** Resolve and validate the connection. Call once during module bootstrap. */
+  async init() {
+    const cfg = this.options.connection;
+    if ("client" in cfg) {
+      this.initModeA(cfg.client);
+      return;
+    }
+    this.mode = "mode-b-owned";
+    this.client = "url" in cfg ? new Redis(cfg.url, { ...cfg.options ?? {}, lazyConnect: false }) : new Redis({ ...cfg.options, lazyConnect: false });
+    await this.waitReady(
+      this.options.connectionReadyTimeoutMs ?? DEFAULT_CONNECTION_READY_TIMEOUT_MS
+    );
+  }
+  /** The resolved Queue-role client. */
+  getClient() {
+    if (!this.client) {
+      throw new QueueException(QUEUE_ERROR_CODES.CONNECTION_INVALID, 500, {
+        reason: "not initialized"
+      });
+    }
+    return this.client;
+  }
+  /** The resolved connection mode. */
+  getMode() {
+    if (!this.mode) {
+      throw new QueueException(QUEUE_ERROR_CODES.CONNECTION_INVALID, 500, {
+        reason: "not initialized"
+      });
+    }
+    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() && this.client) {
+      const client = this.client;
+      await client.quit().catch(() => {
+        client.disconnect();
+      });
+    }
+  }
+  /** Validate and adopt a bring-your-own client for the Queue role. */
+  initModeA(client) {
+    this.mode = "mode-a-byo";
+    this.client = client;
+    if (!isClientUsable(client)) {
+      throw new QueueException(QUEUE_ERROR_CODES.CONNECTION_INVALID, 500, { status: client.status });
+    }
+    const probe = duplicateConnection(client);
+    try {
+      assertBlockingConnection(probe);
+    } finally {
+      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;
+    await new Promise((resolve, reject) => {
+      const cleanup = () => {
+        clearTimeout(timer);
+        client.off("ready", onReady);
+        client.off("error", onError);
+      };
+      const onReady = () => {
+        cleanup();
+        resolve();
+      };
+      const onError = (err) => {
+        cleanup();
+        reject(err);
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new QueueException(QUEUE_ERROR_CODES.CONNECTION_TIMEOUT, 500, { timeoutMs }));
+      }, timeoutMs);
+      client.once("ready", onReady);
+      client.once("error", onError);
+    });
+  }
+};
+ConnectionResolver = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(BYMAX_QUEUE_OPTIONS))
+], ConnectionResolver);
+
+// src/server/utils/validate-job-scheduler-options.ts
+function invalid2(reason) {
+  throw new QueueException(QUEUE_ERROR_CODES.INVALID_REPEAT_OPTIONS, 400, { reason });
+}
+function toEpochMs(date) {
+  return typeof date === "number" ? date : Date.parse(date);
+}
+function validateJobSchedulerOptions(repeat) {
+  const shape = repeat;
+  if (shape === null || typeof shape !== "object" || Array.isArray(shape)) {
+    invalid2("repeat must be an object declaring either pattern or every");
+  }
+  const hasPattern = "pattern" in repeat;
+  const hasEvery = "every" in repeat;
+  if (hasPattern === hasEvery) {
+    invalid2("exactly one of pattern | every is required");
+  }
+  if ("pattern" in repeat && (typeof repeat.pattern !== "string" || repeat.pattern.trim() === "")) {
+    invalid2("pattern must be a non-empty string");
+  }
+  if ("every" in repeat && (!Number.isInteger(repeat.every) || repeat.every <= 0)) {
+    invalid2("every must be a positive integer");
+  }
+  if (repeat.endDate !== void 0) {
+    const endMs = toEpochMs(repeat.endDate);
+    if (Number.isNaN(endMs) || endMs <= Date.now()) {
+      invalid2("endDate must be in the future");
+    }
+  }
+}
+
+// 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}`);
+  });
+}
+
+// src/server/services/queue.service.ts
+var MAX_BULK_SIZE = 1e3;
+function isOperationalError(err) {
+  return typeof err?.code === "string";
+}
+var QueueService = class {
+  constructor(connection, options) {
+    this.connection = connection;
+    this.options = options;
+  }
+  connection;
+  options;
+  logger = new Logger(QueueService.name);
+  queues = /* @__PURE__ */ new Map();
+  /**
+   * 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 = this.queues.get(queueName);
+    if (existing) return existing;
+    const queue = new Queue(queueName, {
+      connection: this.connection.getClient(),
+      prefix: this.options.prefix,
+      defaultJobOptions: this.options.defaultJobOptions,
+      ...this.options.queueOptions,
+      ...this.options.telemetry ? { telemetry: this.options.telemetry } : {},
+      ...overrides
+    });
+    attachDefaultErrorListener(queue, this.logger, "Queue", queueName);
+    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.
+   *
+   * 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.
+   *   await queueService.enqueue('search', 'reindex', { term }, {
+   *     deduplication: { id: `reindex:${term}`, 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(QUEUE_ERROR_CODES.BULK_ENQUEUE_FAILED, 500, {
+        reason: "batch size exceeds limit",
+        limit: MAX_BULK_SIZE,
+        received: jobs.length
+      });
+    }
+    try {
+      const created = await this.queueFor(queueName).addBulk(
+        jobs.map((job) => ({
+          name: job.name,
+          data: job.data,
+          ...job.options === void 0 ? {} : { opts: job.options }
+        }))
+      );
+      return created;
+    } catch (err) {
+      throw new QueueException(QUEUE_ERROR_CODES.BULK_ENQUEUE_FAILED, 500, {
+        cause: err.message
+      });
+    }
+  }
+  /**
+   * 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",
+      "active",
+      "completed",
+      "failed",
+      "delayed",
+      "paused"
+    );
+    return {
+      queue: queueName,
+      counts,
+      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);
+    const jobTemplate = {
+      name: template?.name ?? schedulerId,
+      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, 400, {
+          reason: "pattern must be a valid cron expression (5- or 6-field)"
+        });
+      }
+    }
+    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 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 this.queues.values()) {
+      await queue.close().catch(() => void 0);
+    }
+    this.queues.clear();
+  }
+};
+QueueService = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(ConnectionResolver)),
+  __decorateParam(1, Inject(BYMAX_QUEUE_RESOLVED_OPTIONS))
+], QueueService);
+var FlowService = class {
+  logger = new Logger(FlowService.name);
+  producer;
+  constructor(connection, enabled, prefix, telemetry) {
+    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, 503);
+    }
+    return this.producer;
+  }
+};
+FlowService = __decorateClass([
+  Injectable()
+], FlowService);
+var MetricsService = class {
+  constructor(queueService, enabled, ttlMs) {
+    this.queueService = queueService;
+    this.enabled = enabled;
+    this.ttlMs = ttlMs;
+  }
+  queueService;
+  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);
+    if (entry && entry.expiresAt > Date.now()) {
+      return entry.metrics;
+    }
+    const metrics = await this.queueService.getMetrics(queueName);
+    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) {
+      this.cache.clear();
+      return;
+    }
+    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, 503);
+    }
+  }
+};
+MetricsService = __decorateClass([
+  Injectable()
+], MetricsService);
+var WorkerRegistry = class {
+  constructor(connection, options) {
+    this.connection = connection;
+    this.options = options;
+  }
+  connection;
+  options;
+  logger = new Logger(WorkerRegistry.name);
+  entries = /* @__PURE__ */ new Map();
+  /**
+   * 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);
+    this.validateOptions(options);
+    const conn = duplicateConnection(this.connection.getClient());
+    const bullOpts = this.buildBullOptions(options, conn);
+    let worker;
+    try {
+      worker = new Worker(queueName, handler, bullOpts);
+    } catch (cause) {
+      conn.disconnect();
+      throw new QueueException(QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED, 500, {
+        queueName,
+        cause: cause instanceof Error ? cause.message : String(cause)
+      });
+    }
+    attachDefaultErrorListener(worker, this.logger, "Worker", queueName);
+    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);
+    this.guardDuplicate(queueName);
+    this.validateOptions(options);
+    const conn = duplicateConnection(this.connection.getClient());
+    const bullOpts = this.buildBullOptions(options, conn);
+    if (options?.useWorkerThreads !== void 0) {
+      bullOpts.useWorkerThreads = options.useWorkerThreads;
+    }
+    let worker;
+    try {
+      worker = new Worker(queueName, processorFile, bullOpts);
+    } catch (cause) {
+      conn.disconnect();
+      throw new QueueException(QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED, 500, {
+        queueName,
+        cause: cause instanceof Error ? cause.message : String(cause)
+      });
+    }
+    attachDefaultErrorListener(worker, this.logger, "Worker", queueName);
+    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 = this.entries.get(queueName);
+    if (!entry) return;
+    await entry.worker.close();
+    await this.closeConnection(entry.connection);
+    this.entries.delete(queueName);
+  }
+  /**
+   * Returns the queue names of all currently registered workers.
+   *
+   * @returns An immutable array of queue names.
+   */
+  list() {
+    return Array.from(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(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(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();
+    } catch {
+      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 (this.entries.has(queueName)) {
+      throw new QueueException(QUEUE_ERROR_CODES.DUPLICATE_PROCESSOR, 500, { queueName });
+    }
+  }
+  /**
+   * 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) {
+        throw new QueueException(QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED, 500, {
+          reason: "concurrency must be >= 1",
+          actual: opts.concurrency
+        });
+      }
+      if (opts.concurrency > MAX_WORKER_CONCURRENCY) {
+        throw new QueueException(QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED, 500, {
+          reason: `concurrency must be <= ${MAX_WORKER_CONCURRENCY.toString()}`,
+          actual: opts.concurrency
+        });
+      }
+    }
+    if (opts?.limiter !== void 0) {
+      if (opts.limiter.max < 1) {
+        throw new QueueException(QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED, 500, {
+          reason: "limiter.max must be >= 1",
+          actual: opts.limiter.max
+        });
+      }
+      if (opts.limiter.duration < 1) {
+        throw new QueueException(QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED, 500, {
+          reason: "limiter.duration must be >= 1",
+          actual: opts.limiter.duration
+        });
+      }
+    }
+  }
+  /**
+   * 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:") {
+        throw new QueueException(QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED, 500, {
+          reason: "processorFile URL must use the file: protocol"
+        });
+      }
+      this.assertProcessorExtension(processorFile.pathname);
+      return;
+    }
+    if (!isAbsolute(processorFile)) {
+      throw new QueueException(QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED, 500, {
+        reason: "processorFile must be an absolute path"
+      });
+    }
+    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))) {
+      throw new QueueException(QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED, 500, {
+        reason: "processorFile must have a .js, .cjs, or .mjs extension"
+      });
+    }
+  }
+  /**
+   * 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;
+    if (opts?.lockDuration !== void 0) result.lockDuration = opts.lockDuration;
+    if (opts?.stalledInterval !== void 0) result.stalledInterval = opts.stalledInterval;
+    if (this.options.telemetry !== void 0) result.telemetry = this.options.telemetry;
+    return result;
+  }
+};
+WorkerRegistry = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(ConnectionResolver)),
+  __decorateParam(1, Inject(BYMAX_QUEUE_RESOLVED_OPTIONS))
+], WorkerRegistry);
+var QueueEventsRegistry = class {
+  constructor(connection, options) {
+    this.connection = connection;
+    this.options = options;
+  }
+  connection;
+  options;
+  logger = new Logger(QueueEventsRegistry.name);
+  events = /* @__PURE__ */ new Map();
+  connections = /* @__PURE__ */ new Map();
+  /**
+   * 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 = this.events.get(queueName);
+    if (existing) return existing;
+    const conn = duplicateConnection(this.connection.getClient());
+    let qe;
+    try {
+      qe = new QueueEvents(queueName, { connection: conn, prefix: this.options.prefix });
+    } catch (err) {
+      conn.disconnect();
+      throw err;
+    }
+    attachDefaultErrorListener(qe, this.logger, "QueueEvents", queueName);
+    this.events.set(queueName, qe);
+    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(this.events.keys());
+  }
+  /**
+   * Returns the live `QueueEvents` map. Intended for the shutdown orchestrator.
+   *
+   * @returns A read-only view of the internal map.
+   */
+  getAll() {
+    return 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(this.connections);
+  }
+};
+QueueEventsRegistry = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(ConnectionResolver)),
+  __decorateParam(1, Inject(BYMAX_QUEUE_RESOLVED_OPTIONS))
+], QueueEventsRegistry);
+
+// src/server/decorators/metadata-keys.constants.ts
+var PROCESSOR_METADATA_KEY = /* @__PURE__ */ Symbol("bymax_queue:processor");
+var PROCESS_HANDLERS_METADATA_KEY = /* @__PURE__ */ Symbol("bymax_queue:process_handlers");
+var WORKER_EVENT_LISTENERS_METADATA_KEY = /* @__PURE__ */ Symbol("bymax_queue:worker_event_listeners");
+var QUEUE_EVENT_LISTENERS_METADATA_KEY = /* @__PURE__ */ Symbol("bymax_queue:queue_event_listeners");
+
+// src/server/services/processor-discovery.service.ts
+var ProcessorDiscoveryService = class {
+  constructor(discovery, workers, events) {
+    this.discovery = discovery;
+    this.workers = workers;
+    this.events = events;
+  }
+  discovery;
+  workers;
+  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) {
+      const instance = wrapper.instance;
+      if (!instance || typeof instance !== "object") continue;
+      const ctor = instance.constructor;
+      const processorMeta = Reflect.getOwnMetadata(PROCESSOR_METADATA_KEY, ctor);
+      if (!processorMeta) continue;
+      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;
+    for (const { jobName, methodKey } of handlers) {
+      const method = instance[methodKey];
+      if (typeof method !== "function") continue;
+      const fn = method.bind(instance);
+      if (jobName !== void 0) {
+        namedHandlers.set(jobName, fn);
+      } else {
+        catchAll = fn;
+      }
+    }
+    return (job) => {
+      const specific = namedHandlers.get(job.name);
+      if (specific) return specific(job);
+      if (catchAll) return catchAll(job);
+      return Promise.reject(
+        new Error(
+          `No handler registered for job name "${job.name}" on queue \u2014 add a matching @Process("name") or a catch-all @Process() method.`
+        )
+      );
+    };
+  }
+  /**
+   * 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;
+    if (this.registeredQueues.has(queueName)) {
+      throw new QueueException(QUEUE_ERROR_CODES.DUPLICATE_PROCESSOR, 500, { queueName });
+    }
+    this.registeredQueues.add(queueName);
+    if (_warnedNoConcurrency) {
+      this.logger.warn(
+        `Queue "${queueName}": concurrency was not specified \u2014 defaulting to concurrency=${String(DEFAULT_WORKER_CONCURRENCY)}. Set an explicit concurrency for production workloads.`
+      );
+    }
+    const handlers = Reflect.getOwnMetadata(PROCESS_HANDLERS_METADATA_KEY, ctor) ?? [];
+    const dispatcher = this.buildDispatcher(instance, handlers);
+    const worker = this.workers.register({
+      queueName,
+      handler: dispatcher,
+      options: workerOptions
+    });
+    const workerListeners = Reflect.getOwnMetadata(WORKER_EVENT_LISTENERS_METADATA_KEY, ctor) ?? [];
+    const workerEmitter = worker;
+    for (const { eventName, methodKey } of workerListeners) {
+      const method = instance[methodKey];
+      if (typeof method === "function") {
+        workerEmitter.on(eventName, method.bind(instance));
+      }
+    }
+    const queueListeners = Reflect.getOwnMetadata(QUEUE_EVENT_LISTENERS_METADATA_KEY, ctor) ?? [];
+    if (queueListeners.length > 0) {
+      const qe = this.events.getOrCreate(queueName);
+      const qeEmitter = qe;
+      for (const { eventName, methodKey } of queueListeners) {
+        const method = instance[methodKey];
+        if (typeof method === "function") {
+          qeEmitter.on(eventName, method.bind(instance));
+        }
+      }
+    }
+  }
+};
+ProcessorDiscoveryService = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(DiscoveryService)),
+  __decorateParam(1, Inject(WorkerRegistry)),
+  __decorateParam(2, Inject(QueueEventsRegistry))
+], ProcessorDiscoveryService);
+var QueueLifecycle = class {
+  constructor(workers, events, queues, flow, connection, resolved) {
+    this.workers = workers;
+    this.events = events;
+    this.queues = queues;
+    this.flow = flow;
+    this.connection = connection;
+    this.resolved = resolved;
+  }
+  workers;
+  events;
+  queues;
+  flow;
+  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).
+   */
+  async onModuleDestroy() {
+    const start = Date.now();
+    const forced = await this.closeWorkers();
+    await this.closeQueueEvents();
+    await this.closeDuplicatedConnections();
+    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))`
+    );
+  }
+  /**
+   * 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 {
+        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`
+        );
+        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();
+    closed.catch(() => void 0);
+    try {
+      await Promise.race([
+        closed,
+        new Promise((_resolve, reject) => {
+          timer = setTimeout(() => {
+            reject(new Error("drain timeout"));
+          }, timeoutMs);
+        })
+      ]);
+    } finally {
+      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(),
+      ...this.events.getConnections().values()
+    ];
+    for (const connection of connections) {
+      try {
+        await connection.quit();
+      } catch {
+        connection.disconnect();
+      }
+    }
+  }
+  /**
+   * Drain every cached queue when `drainOnShutdown` is enabled (dev/test only).
+   * Removes waiting and delayed jobs; 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);
+    }
+  }
+  /** 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);
+  }
+};
+QueueLifecycle = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(WorkerRegistry)),
+  __decorateParam(1, Inject(QueueEventsRegistry)),
+  __decorateParam(2, Inject(QueueService)),
+  __decorateParam(3, Inject(FlowService)),
+  __decorateParam(4, Inject(ConnectionResolver)),
+  __decorateParam(5, Inject(BYMAX_QUEUE_RESOLVED_OPTIONS))
+], QueueLifecycle);
+
+// src/server/bymax-queue.module.ts
+var { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } = 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);
+    const base = super.forRoot(options);
+    return {
+      ...base,
+      imports: [DiscoveryModule],
+      providers: [
+        ...base.providers ?? [],
+        { provide: BYMAX_QUEUE_RESOLVED_OPTIONS, useValue: resolved },
+        {
+          provide: FlowService,
+          useFactory: (conn) => new FlowService(conn, resolved.flows.enabled, resolved.prefix, resolved.telemetry),
+          inject: [ConnectionResolver]
+        },
+        {
+          provide: MetricsService,
+          useFactory: (qs) => new MetricsService(qs, resolved.metrics.enabled, resolved.metrics.cacheTtlMs),
+          inject: [QueueService]
+        },
+        ...BymaxQueueModule.buildCoreProviders()
+      ],
+      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 {
+      ...base,
+      imports: [DiscoveryModule, ...base.imports ?? []],
+      providers: [
+        ...base.providers ?? [],
+        {
+          provide: BYMAX_QUEUE_RESOLVED_OPTIONS,
+          useFactory: (opts) => {
+            validateOptions(opts);
+            return applyDefaults(opts);
+          },
+          inject: [MODULE_OPTIONS_TOKEN]
+        },
+        {
+          provide: FlowService,
+          useFactory: (conn, resolved) => new FlowService(conn, resolved.flows.enabled, resolved.prefix, resolved.telemetry),
+          inject: [ConnectionResolver, BYMAX_QUEUE_RESOLVED_OPTIONS]
+        },
+        {
+          provide: MetricsService,
+          useFactory: (qs, resolved) => new MetricsService(qs, resolved.metrics.enabled, resolved.metrics.cacheTtlMs),
+          inject: [QueueService, BYMAX_QUEUE_RESOLVED_OPTIONS]
+        },
+        ...BymaxQueueModule.buildCoreProviders()
+      ],
+      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 },
+      {
+        provide: ConnectionResolver,
+        useFactory: async (opts) => {
+          const resolver = new ConnectionResolver(opts);
+          await resolver.init();
+          return resolver;
+        },
+        inject: [BYMAX_QUEUE_OPTIONS]
+      },
+      {
+        provide: BYMAX_QUEUE_REDIS_CLIENT,
+        useFactory: (resolver) => resolver.getClient(),
+        inject: [ConnectionResolver]
+      },
+      {
+        provide: BYMAX_QUEUE_CONNECTION_MODE,
+        useFactory: (resolver) => resolver.getMode(),
+        inject: [ConnectionResolver]
+      },
+      QueueService,
+      WorkerRegistry,
+      QueueEventsRegistry,
+      ProcessorDiscoveryService,
+      QueueLifecycle
+    ];
+  }
+  /**
+   * The public exports shared by both registration paths.
+   *
+   * @returns A fresh exports list (services and injection tokens).
+   */
+  static buildExports() {
+    return [
+      QueueService,
+      FlowService,
+      MetricsService,
+      ConnectionResolver,
+      WorkerRegistry,
+      QueueEventsRegistry,
+      BYMAX_QUEUE_OPTIONS,
+      BYMAX_QUEUE_RESOLVED_OPTIONS,
+      BYMAX_QUEUE_REDIS_CLIENT,
+      BYMAX_QUEUE_CONNECTION_MODE
+    ];
+  }
+};
+BymaxQueueModule = __decorateClass([
+  Module({})
+], BymaxQueueModule);
+function Processor(queueName, options) {
+  return (target) => {
+    const concurrencyOmitted = options?.concurrency === void 0;
+    const metadata = {
+      queueName,
+      workerOptions: {
+        concurrency: DEFAULT_WORKER_CONCURRENCY,
+        autorun: true,
+        ...options
+      },
+      ...concurrencyOmitted ? { _warnedNoConcurrency: true } : {}
+    };
+    Reflect.defineMetadata(PROCESSOR_METADATA_KEY, metadata, target);
+  };
+}
+function Process(jobName) {
+  return (target, propertyKey) => {
+    const existing = Reflect.getOwnMetadata(PROCESS_HANDLERS_METADATA_KEY, target.constructor) ?? [];
+    const entry = jobName !== void 0 ? { jobName, methodKey: propertyKey } : { methodKey: propertyKey };
+    Reflect.defineMetadata(PROCESS_HANDLERS_METADATA_KEY, [...existing, entry], target.constructor);
+  };
+}
+function OnWorkerEvent(eventName) {
+  return (target, propertyKey) => {
+    const existing = Reflect.getOwnMetadata(
+      WORKER_EVENT_LISTENERS_METADATA_KEY,
+      target.constructor
+    ) ?? [];
+    Reflect.defineMetadata(
+      WORKER_EVENT_LISTENERS_METADATA_KEY,
+      [...existing, { eventName, methodKey: propertyKey }],
+      target.constructor
+    );
+  };
+}
+function OnQueueEvent(eventName) {
+  return (target, propertyKey) => {
+    const existing = Reflect.getOwnMetadata(
+      QUEUE_EVENT_LISTENERS_METADATA_KEY,
+      target.constructor
+    ) ?? [];
+    Reflect.defineMetadata(
+      QUEUE_EVENT_LISTENERS_METADATA_KEY,
+      [...existing, { eventName, methodKey: propertyKey }],
+      target.constructor
+    );
+  };
+}
+
+// src/shared/constants/job-status.ts
+var JOB_STATUS = {
+  WAITING: "waiting",
+  ACTIVE: "active",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  DELAYED: "delayed",
+  PAUSED: "paused"
+};
+
+export { BYMAX_QUEUE_CONNECTION_MODE, BYMAX_QUEUE_OPTIONS, BYMAX_QUEUE_REDIS_CLIENT, BYMAX_QUEUE_RESOLVED_OPTIONS, BymaxQueueModule, ConnectionResolver, DEFAULT_JOB_OPTIONS, DEFAULT_METRICS_CACHE_TTL_MS, DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS, DEFAULT_WORKER_CONCURRENCY, FlowService, JOB_STATUS, MAX_WORKER_CONCURRENCY, MetricsService, OnQueueEvent, OnWorkerEvent, Process, Processor, QUEUE_ERROR_CODES, QUEUE_ERROR_MESSAGES, QueueEventsRegistry, QueueException, QueueService, WorkerRegistry };