@bymax-one/nest-queue 1.2.2 → 1.2.4

package/CHANGELOG.md

@@ -7,6 +7,87 @@ versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [Unreleased]
+
+---
+
+## [1.2.4] — 2026-10-30
+
+No action required: behaviour, the public API, the types and the peer ranges are unchanged.
+
+The status codes a `QueueException` carries are the same as in 1.2.3, but the bundle under `dist/`
+is not byte-identical, and the differences are listed below so a reader does not have to take
+"no change" on trust.
+
+### Changed
+
+- `QueueException` is now thrown with the named `HttpStatus` members (`BAD_REQUEST`,
+  `INTERNAL_SERVER_ERROR`, `SERVICE_UNAVAILABLE`) instead of the numbers 400, 500 and 503, at every
+  call site. The values are the same; the change satisfies `no-unsafe-enum-assignment`. Against a
+  fresh build of 1.2.3, the CommonJS bundle is identical once those members are replaced by their
+  numeric values, the ES module bundle differs only in the order of its `@nestjs/common` imports and
+  in line wrapping, and the type declarations differ in one JSDoc line (`FlowService`, which now
+  names `HttpStatus.SERVICE_UNAVAILABLE`).
+
+### Security
+
+Not shipped:
+
+- Dependency resolution of the tooling the repository builds and tests with was raised to patched
+  versions: `fastify`, `undici`, `fast-uri`, `js-yaml`, `brace-expansion`, `qs`, `zod`,
+  `handlebars`, `@grpc/grpc-js` and `@nestjs/platform-fastify`. None of these ships in the package,
+  which still declares `"dependencies": {}`; they reach it only through development and example-app
+  tooling.
+- `osv-scanner.toml` ignores `GHSA-gcqx-w48m-w2h4` (`deepmerge` 4.3.1, no patched release) until
+  2027-01-27. The package is reached only through `jest-config`, a development dependency.
+
+### Documentation
+
+- The README supply-chain wording now says that third-party GitHub Actions are pinned to a commit SHA,
+  which is what the workflows do; the organisation's own reusable workflows follow a version tag.
+
+### Internal
+
+Not shipped:
+
+- Tests kill the four mutants that survived the full mutation run, and the one equivalent mutant is
+  disabled in place with the reason beside it. The mutation score is 100%.
+- The README snippet check (`scripts/check-published-surface.mjs`) decides whether a snippet
+  declares a receiver from the parsed snippet rather than from its text, so decorated constructor
+  parameters, object-literal keys and JSX are classified correctly.
+- Development and GitHub Actions dependencies were updated (Stryker, Jest, ts-jest, Prettier,
+  typescript-eslint, testcontainers, NestJS 11.2.x, and the CodeQL, pnpm, harden-runner, TruffleHog
+  and setup-node actions).
+- The shared review-rules block in `AGENTS.md` was synchronised with its canonical copy.
+- `SECURITY.md`, `CONTRIBUTING.md`, `CLAUDE.md`, `AGENTS.md` and the mutation-testing documents were
+  brought in line with the current configuration.
+
+---
+
+## [1.2.3] — 2026-09-05
+
+**Nothing that runs in this package changed.** A fresh build of the release commit was packed and
+compared against the published 1.2.2 tarball: `dist/` is identical file for file, and `package.json`
+differs only in the version string. The remaining difference is this CHANGELOG entry, which ships
+because `CHANGELOG.md` does.
+
+It exists because the estate releases on a cadence, so a library whose artifact is unchanged
+publishes anyway and says so rather than implying a benefit it does not deliver. **There is no
+reason to upgrade from 1.2.2**, and a consumer on `^1.2.0` gains nothing by resolving to it.
+
+### Internal
+
+Not shipped — `files` is `dist`, `LICENSE`, `README.md`, `CHANGELOG.md`, and the only file touched
+since 1.2.2 is `AGENTS.md`:
+
+- The shared review-rules block was synchronised with its canonical copy, bringing in an invariant
+  for keys built from more than one field — the generalised form of the deduplication defect this
+  package corrected in 1.2.2.
+- Two repository-specific review rules were corrected: one rested its case on a defect that had
+  since been fixed, so the claim had become false; the other required an authorship finding to
+  quote a resolvable commit id, a criterion the shared block superseded by placing author and
+  committer identity out of scope entirely.
+
 ## [1.2.2] — 2026-09-04
 
 **1.2.1 was tagged but never published**, so this release carries its documentation fix as well
@@ -528,6 +609,9 @@ v6 peer range.
 
 ---
 
+[Unreleased]: https://github.com/bymaxone/nest-queue/compare/v1.2.4...HEAD
+[1.2.4]: https://github.com/bymaxone/nest-queue/compare/v1.2.3...v1.2.4
+[1.2.3]: https://github.com/bymaxone/nest-queue/compare/v1.2.2...v1.2.3
 [1.2.2]: https://github.com/bymaxone/nest-queue/compare/v1.2.1...v1.2.2
 [1.2.1]: https://github.com/bymaxone/nest-queue/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/bymaxone/nest-queue/compare/v1.0.11...v1.2.0

package/README.md

@@ -771,7 +771,7 @@ key will do it twice at some point.
 | Namespacing       | `prefix` applied uniformly to `Queue`, `Worker`, `QueueEvents` and `FlowProducer`                                                                                                           |
 | Connection policy | `maxRetriesPerRequest: null` confined to duplicated consumer connections; producers keep fail-fast retries                                                                                  |
 | Delivery          | At-least-once with a bounded drain; unacknowledged work is re-queued by BullMQ's stalled check                                                                                              |
-| Supply chain      | `dependencies: {}`; SHA-pinned Actions, OSV-Scanner, TruffleHog, OpenSSF Scorecard; npm publish over OIDC                                                                                   |
+| Supply chain      | `dependencies: {}`; SHA-pinned third-party Actions, OSV-Scanner, TruffleHog, OpenSSF Scorecard; npm publish over OIDC                                                                       |
 | Input validation  | Options validated at bootstrap; cron patterns validated by BullMQ's own parser, never a hand-rolled regex                                                                                   |
 
 > [!IMPORTANT]
@@ -805,7 +805,7 @@ key will do it twice at some point.
   module-resolution mode would (all four `attw` quadrants green, `node10` included), and
   `pnpm smoke` resolves the packed tarball from a real consumer in ESM _and_ CommonJS.
 - **Bundle budgets** enforced (`pnpm size`): server ≤ 18 KiB brotli, shared ≤ 2.5 KiB.
-- **Supply chain:** SHA-pinned GitHub Actions, OSV-Scanner, TruffleHog, OpenSSF Scorecard,
+- **Supply chain:** SHA-pinned third-party GitHub Actions, OSV-Scanner, TruffleHog, OpenSSF Scorecard,
   npm publish with provenance (OIDC).
 
 ```bash

package/dist/server/index.cjs

@@ -80,7 +80,9 @@ var QueueException = class extends common.HttpException {
 
 // src/server/config/validate-options.ts
 function invalid(reason) {
-  throw new QueueException(QUEUE_ERROR_CODES.INVALID_OPTIONS, 500, { reason });
+  throw new QueueException(QUEUE_ERROR_CODES.INVALID_OPTIONS, common.HttpStatus.INTERNAL_SERVER_ERROR, {
+    reason
+  });
 }
 function validateOptions(opts) {
   const cfg = opts.connection;
@@ -152,15 +154,17 @@ 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
-    });
+    throw new QueueException(
+      QUEUE_ERROR_CODES.CONNECTION_REQUIRES_NULL_RETRIES,
+      common.HttpStatus.INTERNAL_SERVER_ERROR,
+      {
+        actualValue: actualValue ?? null,
+        expectedValue: null
+      }
+    );
   }
 }
 function isClientUsable(client) {
@@ -217,18 +221,26 @@ exports.ConnectionResolver = class ConnectionResolver {
   /** The resolved Queue-role client. */
   getClient() {
     if (!__privateGet(this, _client)) {
-      throw new QueueException(QUEUE_ERROR_CODES.CONNECTION_INVALID, 500, {
-        reason: "not initialized"
-      });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.CONNECTION_INVALID,
+        common.HttpStatus.INTERNAL_SERVER_ERROR,
+        {
+          reason: "not initialized"
+        }
+      );
     }
     return __privateGet(this, _client);
   }
   /** The resolved connection mode. */
   getMode() {
     if (!this.mode) {
-      throw new QueueException(QUEUE_ERROR_CODES.CONNECTION_INVALID, 500, {
-        reason: "not initialized"
-      });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.CONNECTION_INVALID,
+        common.HttpStatus.INTERNAL_SERVER_ERROR,
+        {
+          reason: "not initialized"
+        }
+      );
     }
     return this.mode;
   }
@@ -250,7 +262,11 @@ exports.ConnectionResolver = class ConnectionResolver {
     this.mode = "mode-a-byo";
     __privateSet(this, _client, client);
     if (!isClientUsable(client)) {
-      throw new QueueException(QUEUE_ERROR_CODES.CONNECTION_INVALID, 500, { status: client.status });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.CONNECTION_INVALID,
+        common.HttpStatus.INTERNAL_SERVER_ERROR,
+        { status: client.status }
+      );
     }
     const probe = duplicateConnection(client);
     try {
@@ -279,7 +295,13 @@ exports.ConnectionResolver = class ConnectionResolver {
       };
       const timer = setTimeout(() => {
         cleanup();
-        reject(new QueueException(QUEUE_ERROR_CODES.CONNECTION_TIMEOUT, 500, { timeoutMs }));
+        reject(
+          new QueueException(
+            QUEUE_ERROR_CODES.CONNECTION_TIMEOUT,
+            common.HttpStatus.INTERNAL_SERVER_ERROR,
+            { timeoutMs }
+          )
+        );
       }, timeoutMs);
       client.once("ready", onReady);
       client.once("error", onError);
@@ -292,10 +314,10 @@ exports.ConnectionResolver = __decorateClass([
   common.Injectable(),
   __decorateParam(0, common.Inject(BYMAX_QUEUE_OPTIONS))
 ], exports.ConnectionResolver);
-
-// src/server/utils/validate-job-scheduler-options.ts
 function invalid2(reason) {
-  throw new QueueException(QUEUE_ERROR_CODES.INVALID_REPEAT_OPTIONS, 400, { reason });
+  throw new QueueException(QUEUE_ERROR_CODES.INVALID_REPEAT_OPTIONS, common.HttpStatus.BAD_REQUEST, {
+    reason
+  });
 }
 function toEpochMs(date) {
   return typeof date === "number" ? date : Date.parse(date);
@@ -435,11 +457,15 @@ exports.QueueService = class QueueService {
    */
   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
-      });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.BULK_ENQUEUE_FAILED,
+        common.HttpStatus.INTERNAL_SERVER_ERROR,
+        {
+          reason: "batch size exceeds limit",
+          limit: MAX_BULK_SIZE,
+          received: jobs.length
+        }
+      );
     }
     try {
       const created = await this.queueFor(queueName).addBulk(
@@ -451,9 +477,13 @@ exports.QueueService = class QueueService {
       );
       return created;
     } catch (err) {
-      throw new QueueException(QUEUE_ERROR_CODES.BULK_ENQUEUE_FAILED, 500, {
-        cause: err.message
-      });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.BULK_ENQUEUE_FAILED,
+        common.HttpStatus.INTERNAL_SERVER_ERROR,
+        {
+          cause: err.message
+        }
+      );
     }
   }
   /**
@@ -529,7 +559,7 @@ exports.QueueService = class QueueService {
         return job2;
       } catch (err) {
         if (isOperationalError(err)) throw err;
-        throw new QueueException(QUEUE_ERROR_CODES.INVALID_REPEAT_OPTIONS, 400, {
+        throw new QueueException(QUEUE_ERROR_CODES.INVALID_REPEAT_OPTIONS, common.HttpStatus.BAD_REQUEST, {
           reason: "pattern must be a valid cron expression (5- or 6-field)"
         });
       }
@@ -682,7 +712,7 @@ exports.FlowService = class FlowService {
    */
   requireProducer() {
     if (!this.producer) {
-      throw new QueueException(QUEUE_ERROR_CODES.FLOW_DISABLED, 503);
+      throw new QueueException(QUEUE_ERROR_CODES.FLOW_DISABLED, common.HttpStatus.SERVICE_UNAVAILABLE);
     }
     return this.producer;
   }
@@ -750,7 +780,7 @@ exports.MetricsService = class MetricsService {
    */
   ensureEnabled() {
     if (!this.enabled) {
-      throw new QueueException(QUEUE_ERROR_CODES.METRICS_DISABLED, 503);
+      throw new QueueException(QUEUE_ERROR_CODES.METRICS_DISABLED, common.HttpStatus.SERVICE_UNAVAILABLE);
     }
   }
 };
@@ -791,10 +821,14 @@ exports.WorkerRegistry = class WorkerRegistry {
       worker = new bullmq.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)
-      });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+        common.HttpStatus.INTERNAL_SERVER_ERROR,
+        {
+          queueName,
+          cause: cause instanceof Error ? cause.message : String(cause)
+        }
+      );
     }
     attachDefaultErrorListener(worker, this.logger, "Worker", queueName);
     __privateGet(this, _entries).set(queueName, { worker, connection: conn });
@@ -830,10 +864,14 @@ exports.WorkerRegistry = class WorkerRegistry {
       worker = new bullmq.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)
-      });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+        common.HttpStatus.INTERNAL_SERVER_ERROR,
+        {
+          queueName,
+          cause: cause instanceof Error ? cause.message : String(cause)
+        }
+      );
     }
     attachDefaultErrorListener(worker, this.logger, "Worker", queueName);
     __privateGet(this, _entries).set(queueName, { worker, connection: conn });
@@ -906,7 +944,11 @@ exports.WorkerRegistry = class WorkerRegistry {
    */
   guardDuplicate(queueName) {
     if (__privateGet(this, _entries).has(queueName)) {
-      throw new QueueException(QUEUE_ERROR_CODES.DUPLICATE_PROCESSOR, 500, { queueName });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.DUPLICATE_PROCESSOR,
+        common.HttpStatus.INTERNAL_SERVER_ERROR,
+        { queueName }
+      );
     }
   }
   /**
@@ -920,30 +962,46 @@ exports.WorkerRegistry = class WorkerRegistry {
   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
-        });
+        throw new QueueException(
+          QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+          common.HttpStatus.INTERNAL_SERVER_ERROR,
+          {
+            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
-        });
+        throw new QueueException(
+          QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+          common.HttpStatus.INTERNAL_SERVER_ERROR,
+          {
+            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
-        });
+        throw new QueueException(
+          QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+          common.HttpStatus.INTERNAL_SERVER_ERROR,
+          {
+            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
-        });
+        throw new QueueException(
+          QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+          common.HttpStatus.INTERNAL_SERVER_ERROR,
+          {
+            reason: "limiter.duration must be >= 1",
+            actual: opts.limiter.duration
+          }
+        );
       }
     }
   }
@@ -959,17 +1017,25 @@ exports.WorkerRegistry = class WorkerRegistry {
   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"
-        });
+        throw new QueueException(
+          QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+          common.HttpStatus.INTERNAL_SERVER_ERROR,
+          {
+            reason: "processorFile URL must use the file: protocol"
+          }
+        );
       }
       this.assertProcessorExtension(processorFile.pathname);
       return;
     }
     if (!path.isAbsolute(processorFile)) {
-      throw new QueueException(QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED, 500, {
-        reason: "processorFile must be an absolute path"
-      });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+        common.HttpStatus.INTERNAL_SERVER_ERROR,
+        {
+          reason: "processorFile must be an absolute path"
+        }
+      );
     }
     this.assertProcessorExtension(processorFile);
   }
@@ -983,9 +1049,13 @@ exports.WorkerRegistry = class WorkerRegistry {
   assertProcessorExtension(filePath) {
     const allowedExtensions = /* @__PURE__ */ new Set([".js", ".cjs", ".mjs"]);
     if (!allowedExtensions.has(path.extname(filePath))) {
-      throw new QueueException(QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED, 500, {
-        reason: "processorFile must have a .js, .cjs, or .mjs extension"
-      });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+        common.HttpStatus.INTERNAL_SERVER_ERROR,
+        {
+          reason: "processorFile must have a .js, .cjs, or .mjs extension"
+        }
+      );
     }
   }
   /**
@@ -1173,7 +1243,11 @@ var ProcessorDiscoveryService = class {
     const { queueName, workerOptions, _warnedNoConcurrency } = processorMeta;
     const ctor = instance.constructor;
     if (this.registeredQueues.has(queueName)) {
-      throw new QueueException(QUEUE_ERROR_CODES.DUPLICATE_PROCESSOR, 500, { queueName });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.DUPLICATE_PROCESSOR,
+        common.HttpStatus.INTERNAL_SERVER_ERROR,
+        { queueName }
+      );
     }
     this.registeredQueues.add(queueName);
     if (_warnedNoConcurrency) {

package/dist/server/index.d.cts

@@ -579,7 +579,7 @@ declare class QueueService {
  *
  * Opt-in: this provider is registered unconditionally so that injecting it never
  * raises `UnknownDependenciesException`; instead, every operation throws
- * `QueueException(FLOW_DISABLED, 503)` when `flows.enabled !== true`.
+ * `QueueException(FLOW_DISABLED, HttpStatus.SERVICE_UNAVAILABLE)` when `flows.enabled !== true`.
  *
  * @example
  * await flowService.add({

package/dist/server/index.d.ts

@@ -579,7 +579,7 @@ declare class QueueService {
  *
  * Opt-in: this provider is registered unconditionally so that injecting it never
  * raises `UnknownDependenciesException`; instead, every operation throws
- * `QueueException(FLOW_DISABLED, 503)` when `flows.enabled !== true`.
+ * `QueueException(FLOW_DISABLED, HttpStatus.SERVICE_UNAVAILABLE)` when `flows.enabled !== true`.
  *
  * @example
  * await flowService.add({

package/dist/server/index.mjs

@@ -1,4 +1,4 @@
-import { Injectable, Inject, ConfigurableModuleBuilder, Module, Logger, HttpException, HttpStatus } from '@nestjs/common';
+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';
@@ -78,7 +78,9 @@ var QueueException = class extends HttpException {
 
 // src/server/config/validate-options.ts
 function invalid(reason) {
-  throw new QueueException(QUEUE_ERROR_CODES.INVALID_OPTIONS, 500, { reason });
+  throw new QueueException(QUEUE_ERROR_CODES.INVALID_OPTIONS, HttpStatus.INTERNAL_SERVER_ERROR, {
+    reason
+  });
 }
 function validateOptions(opts) {
   const cfg = opts.connection;
@@ -150,15 +152,17 @@ 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
-    });
+    throw new QueueException(
+      QUEUE_ERROR_CODES.CONNECTION_REQUIRES_NULL_RETRIES,
+      HttpStatus.INTERNAL_SERVER_ERROR,
+      {
+        actualValue: actualValue ?? null,
+        expectedValue: null
+      }
+    );
   }
 }
 function isClientUsable(client) {
@@ -215,18 +219,26 @@ var ConnectionResolver = class {
   /** The resolved Queue-role client. */
   getClient() {
     if (!__privateGet(this, _client)) {
-      throw new QueueException(QUEUE_ERROR_CODES.CONNECTION_INVALID, 500, {
-        reason: "not initialized"
-      });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.CONNECTION_INVALID,
+        HttpStatus.INTERNAL_SERVER_ERROR,
+        {
+          reason: "not initialized"
+        }
+      );
     }
     return __privateGet(this, _client);
   }
   /** The resolved connection mode. */
   getMode() {
     if (!this.mode) {
-      throw new QueueException(QUEUE_ERROR_CODES.CONNECTION_INVALID, 500, {
-        reason: "not initialized"
-      });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.CONNECTION_INVALID,
+        HttpStatus.INTERNAL_SERVER_ERROR,
+        {
+          reason: "not initialized"
+        }
+      );
     }
     return this.mode;
   }
@@ -248,7 +260,11 @@ var ConnectionResolver = class {
     this.mode = "mode-a-byo";
     __privateSet(this, _client, client);
     if (!isClientUsable(client)) {
-      throw new QueueException(QUEUE_ERROR_CODES.CONNECTION_INVALID, 500, { status: client.status });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.CONNECTION_INVALID,
+        HttpStatus.INTERNAL_SERVER_ERROR,
+        { status: client.status }
+      );
     }
     const probe = duplicateConnection(client);
     try {
@@ -277,7 +293,13 @@ var ConnectionResolver = class {
       };
       const timer = setTimeout(() => {
         cleanup();
-        reject(new QueueException(QUEUE_ERROR_CODES.CONNECTION_TIMEOUT, 500, { timeoutMs }));
+        reject(
+          new QueueException(
+            QUEUE_ERROR_CODES.CONNECTION_TIMEOUT,
+            HttpStatus.INTERNAL_SERVER_ERROR,
+            { timeoutMs }
+          )
+        );
       }, timeoutMs);
       client.once("ready", onReady);
       client.once("error", onError);
@@ -290,10 +312,10 @@ 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 });
+  throw new QueueException(QUEUE_ERROR_CODES.INVALID_REPEAT_OPTIONS, HttpStatus.BAD_REQUEST, {
+    reason
+  });
 }
 function toEpochMs(date) {
   return typeof date === "number" ? date : Date.parse(date);
@@ -433,11 +455,15 @@ var QueueService = class {
    */
   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
-      });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.BULK_ENQUEUE_FAILED,
+        HttpStatus.INTERNAL_SERVER_ERROR,
+        {
+          reason: "batch size exceeds limit",
+          limit: MAX_BULK_SIZE,
+          received: jobs.length
+        }
+      );
     }
     try {
       const created = await this.queueFor(queueName).addBulk(
@@ -449,9 +475,13 @@ var QueueService = class {
       );
       return created;
     } catch (err) {
-      throw new QueueException(QUEUE_ERROR_CODES.BULK_ENQUEUE_FAILED, 500, {
-        cause: err.message
-      });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.BULK_ENQUEUE_FAILED,
+        HttpStatus.INTERNAL_SERVER_ERROR,
+        {
+          cause: err.message
+        }
+      );
     }
   }
   /**
@@ -527,7 +557,7 @@ var QueueService = class {
         return job2;
       } catch (err) {
         if (isOperationalError(err)) throw err;
-        throw new QueueException(QUEUE_ERROR_CODES.INVALID_REPEAT_OPTIONS, 400, {
+        throw new QueueException(QUEUE_ERROR_CODES.INVALID_REPEAT_OPTIONS, HttpStatus.BAD_REQUEST, {
           reason: "pattern must be a valid cron expression (5- or 6-field)"
         });
       }
@@ -680,7 +710,7 @@ var FlowService = class {
    */
   requireProducer() {
     if (!this.producer) {
-      throw new QueueException(QUEUE_ERROR_CODES.FLOW_DISABLED, 503);
+      throw new QueueException(QUEUE_ERROR_CODES.FLOW_DISABLED, HttpStatus.SERVICE_UNAVAILABLE);
     }
     return this.producer;
   }
@@ -748,7 +778,7 @@ var MetricsService = class {
    */
   ensureEnabled() {
     if (!this.enabled) {
-      throw new QueueException(QUEUE_ERROR_CODES.METRICS_DISABLED, 503);
+      throw new QueueException(QUEUE_ERROR_CODES.METRICS_DISABLED, HttpStatus.SERVICE_UNAVAILABLE);
     }
   }
 };
@@ -789,10 +819,14 @@ var WorkerRegistry = class {
       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)
-      });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+        HttpStatus.INTERNAL_SERVER_ERROR,
+        {
+          queueName,
+          cause: cause instanceof Error ? cause.message : String(cause)
+        }
+      );
     }
     attachDefaultErrorListener(worker, this.logger, "Worker", queueName);
     __privateGet(this, _entries).set(queueName, { worker, connection: conn });
@@ -828,10 +862,14 @@ var WorkerRegistry = class {
       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)
-      });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+        HttpStatus.INTERNAL_SERVER_ERROR,
+        {
+          queueName,
+          cause: cause instanceof Error ? cause.message : String(cause)
+        }
+      );
     }
     attachDefaultErrorListener(worker, this.logger, "Worker", queueName);
     __privateGet(this, _entries).set(queueName, { worker, connection: conn });
@@ -904,7 +942,11 @@ var WorkerRegistry = class {
    */
   guardDuplicate(queueName) {
     if (__privateGet(this, _entries).has(queueName)) {
-      throw new QueueException(QUEUE_ERROR_CODES.DUPLICATE_PROCESSOR, 500, { queueName });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.DUPLICATE_PROCESSOR,
+        HttpStatus.INTERNAL_SERVER_ERROR,
+        { queueName }
+      );
     }
   }
   /**
@@ -918,30 +960,46 @@ var WorkerRegistry = class {
   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
-        });
+        throw new QueueException(
+          QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+          HttpStatus.INTERNAL_SERVER_ERROR,
+          {
+            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
-        });
+        throw new QueueException(
+          QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+          HttpStatus.INTERNAL_SERVER_ERROR,
+          {
+            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
-        });
+        throw new QueueException(
+          QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+          HttpStatus.INTERNAL_SERVER_ERROR,
+          {
+            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
-        });
+        throw new QueueException(
+          QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+          HttpStatus.INTERNAL_SERVER_ERROR,
+          {
+            reason: "limiter.duration must be >= 1",
+            actual: opts.limiter.duration
+          }
+        );
       }
     }
   }
@@ -957,17 +1015,25 @@ var WorkerRegistry = class {
   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"
-        });
+        throw new QueueException(
+          QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+          HttpStatus.INTERNAL_SERVER_ERROR,
+          {
+            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"
-      });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+        HttpStatus.INTERNAL_SERVER_ERROR,
+        {
+          reason: "processorFile must be an absolute path"
+        }
+      );
     }
     this.assertProcessorExtension(processorFile);
   }
@@ -981,9 +1047,13 @@ var WorkerRegistry = class {
   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"
-      });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.WORKER_REGISTRATION_FAILED,
+        HttpStatus.INTERNAL_SERVER_ERROR,
+        {
+          reason: "processorFile must have a .js, .cjs, or .mjs extension"
+        }
+      );
     }
   }
   /**
@@ -1171,7 +1241,11 @@ var ProcessorDiscoveryService = class {
     const { queueName, workerOptions, _warnedNoConcurrency } = processorMeta;
     const ctor = instance.constructor;
     if (this.registeredQueues.has(queueName)) {
-      throw new QueueException(QUEUE_ERROR_CODES.DUPLICATE_PROCESSOR, 500, { queueName });
+      throw new QueueException(
+        QUEUE_ERROR_CODES.DUPLICATE_PROCESSOR,
+        HttpStatus.INTERNAL_SERVER_ERROR,
+        { queueName }
+      );
     }
     this.registeredQueues.add(queueName);
     if (_warnedNoConcurrency) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-queue",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "NestJS dynamic module wrapping BullMQ — typed jobs, flows, job schedulers, deduplication, OpenTelemetry, graceful shutdown",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -103,7 +103,7 @@
     "@stryker-mutator/core": "^10.0.0",
     "@stryker-mutator/jest-runner": "^10.0.0",
     "@types/jest": "^30.0.0",
-    "@types/node": "^26.2.0",
+    "@types/node": "^24.19.2",
     "bullmq": "^6.0.0",
     "eslint": "^10.8.1",
     "eslint-config-prettier": "^10.1.8",