@bymax-one/nest-queue 1.2.6 → 1.2.8

package/CHANGELOG.md

@@ -11,6 +11,51 @@ versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.2.8] — 2026-11-01
+
+No action required: behaviour, the public API, the types and the peer ranges are unchanged.
+Measured with `diff -r` of a fresh build against the unpacked 1.2.7 tarball, `dist/` is identical;
+the package otherwise changes in `README.md`, this file and the version in `package.json`.
+
+### Documentation
+
+- **The README now states how many Redis connections the library holds.** A new "Redis connections"
+  section gives the budget measured against Redis 8: 1 for the module in Mode B and none of its own
+  in Mode A, 2 per worker, 2 per queue observed with `@OnQueueEvent`, and none for producers and
+  flows, all released on close. It carries a worked example (20 workers and 5 observed queues hold
+  51 connections in Mode B) and a note on connection quotas of managed Redis plans.
+- **The Mode B description of the connections was wrong.** It said the library opens one connection
+  per worker and per observed queue; each of those holds two, a blocking connection and a command
+  connection.
+
+---
+
+## [1.2.7] — 2026-10-31
+
+Action required if your `connection.url` can be empty or malformed: an invalid or empty
+`connection.url` now fails the boot with `INVALID_OPTIONS`; before 1.2.7 it silently connected to
+`localhost:6379`. A valid `url` needs no change. The public API, the types (`index.d.ts` and
+`index.d.cts` are identical) and the peer ranges are unchanged. Measured with `diff -r` of a fresh
+build against the unpacked 1.2.6 tarball, only the two runtime bundles (`index.mjs`, `index.cjs`)
+differ.
+
+### Fixed
+
+- **`connection.url` is now validated.** `forRoot` refuses a `url` that is not a non-empty string
+  with `INVALID_OPTIONS` ("connection.url must be a non-empty string"). Before, `ioredis` read an
+  absent, empty, whitespace-only, `null` or object `url` as no url at all and connected to
+  `localhost:6379`, and a number as a port, so a missing `REDIS_URL` surfaced as a connection to the
+  wrong server instead of an error. A string `ioredis` cannot parse (`not a url`, `redis://h:abc`)
+  is refused the same way ("connection.url is not a valid Redis URL"), where it used to throw a raw
+  `Invalid URL` from the client constructor. Unix socket paths, `host:port` and `redis://` /
+  `rediss://` URLs, with or without `options`, are unaffected.
+- **A worker that fails to start no longer hides the failure behind a second error.** The
+  `WORKER_REGISTRATION_FAILED` details were built with `String(cause)`, which throws a `TypeError`
+  for a null-prototype value; the cause is now described by a helper that cannot throw, so the
+  registration failure reaches the caller as the typed exception.
+
+---
+
 ## [1.2.6] — 2026-10-31
 
 No action required: behaviour, the public API, the types and the peer ranges are unchanged.
@@ -702,7 +747,9 @@ v6 peer range.
 
 ---
 
-[Unreleased]: https://github.com/bymaxone/nest-queue/compare/v1.2.6...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-queue/compare/v1.2.8...HEAD
+[1.2.8]: https://github.com/bymaxone/nest-queue/compare/v1.2.7...v1.2.8
+[1.2.7]: https://github.com/bymaxone/nest-queue/compare/v1.2.6...v1.2.7
 [1.2.6]: https://github.com/bymaxone/nest-queue/compare/v1.2.5...v1.2.6
 [1.2.5]: https://github.com/bymaxone/nest-queue/compare/v1.2.4...v1.2.5
 [1.2.4]: https://github.com/bymaxone/nest-queue/compare/v1.2.3...v1.2.4

package/README.md

@@ -313,8 +313,41 @@ BymaxQueueModule.forRoot({
 })
 ```
 
-The library opens one connection for queues, one per worker and one per queue that has an
-`@OnQueueEvent` listener. The worker and `QueueEvents` connections carry `maxRetriesPerRequest: null`.
+The library opens one connection for all queues and flows, and two for each worker and for each
+queue that has an `@OnQueueEvent` listener ([the budget is below](#-redis-connections)). The worker
+and `QueueEvents` connections carry `maxRetriesPerRequest: null`.
+
+---
+
+## 🔌 Redis connections
+
+How many connections the library holds is linear in what you register, so you can budget it before
+you deploy. Counts were read from `INFO clients` against Redis 8 with BullMQ 6 and `ioredis` 6, and
+every connection is released when the application context closes.
+
+| What you register                              | Connections held                                                               |
+| ---------------------------------------------- | ------------------------------------------------------------------------------ |
+| The module (Mode B, library-owned connection)  | 1, shared by every producer and every flow                                     |
+| The module (Mode A, your client)               | 0 of its own; your client is yours and is never counted                        |
+| A queue you enqueue to, with `QueueService`    | 0 more: queues share the module's connection                                   |
+| `FlowService` (flows enabled)                  | 0 more                                                                         |
+| Each worker (`@Processor` or `WorkerRegistry`) | 2: a blocking connection that waits for jobs, and a command connection         |
+| Each queue observed with `@OnQueueEvent`       | 2: a blocking connection that reads the event stream, and a command connection |
+
+Producers and flows add nothing, so the cost comes from consumers. The blocking connection of a
+worker cannot be shared: it is parked inside a blocking command until a job arrives.
+
+**Worked example.** One application instance in Mode B with 20 workers and 5 queues observed with
+`@OnQueueEvent` holds 1 + (2 × 20) + (2 × 5) = **51** connections; in Mode A the same instance holds
+50, plus whatever your own client uses. Each instance of the application opens its own set, so three
+instances hold 153.
+
+**Managed Redis.** Hosted Redis plans cap the number of concurrent connections, and a plan sized for
+a handful of clients is exhausted by one instance with a few dozen workers. Multiply the table by
+the number of instances you run (include rolling deploys, where old and new instances overlap) and
+compare it with the limit of your plan; self-managed Redis allows 10 000 by default (`maxclients`).
+In `CLIENT LIST`, the blocking connection of a worker has a name that starts with
+`<prefix>:<base64 of the queue name>`, which identifies it; the command connection is unnamed.
 
 ---
 

package/dist/server/index.cjs

@@ -84,6 +84,19 @@ function invalid(reason) {
     reason
   });
 }
+function isParseableUrl(url) {
+  const candidate = /^rediss?:\/\//i.test(url) ? url : url.startsWith("//") ? `redis:${url}` : `redis://${url}`;
+  if (!URL.canParse(candidate)) return false;
+  const { username, password } = new URL(candidate);
+  let decodable = true;
+  try {
+    decodeURIComponent(username);
+    decodeURIComponent(password);
+  } catch {
+    decodable = false;
+  }
+  return decodable;
+}
 function validateOptions(opts) {
   const cfg = opts.connection;
   if (cfg === null || typeof cfg !== "object") {
@@ -98,6 +111,15 @@ function validateOptions(opts) {
   if (hasClient && (hasUrl || hasOptions)) {
     invalid("connection.client is mutually exclusive with url/options");
   }
+  if (hasUrl) {
+    const url = cfg.url;
+    if (typeof url !== "string" || url.trim() === "") {
+      invalid("connection.url must be a non-empty string");
+    }
+    if (!isParseableUrl(url)) {
+      invalid("connection.url is not a valid Redis URL");
+    }
+  }
   const drainTimeoutMs = opts.shutdown?.drainTimeoutMs;
   if (drainTimeoutMs !== void 0 && drainTimeoutMs <= 0) {
     invalid("shutdown.drainTimeoutMs must be > 0");
@@ -787,6 +809,20 @@ exports.MetricsService = class MetricsService {
 exports.MetricsService = __decorateClass([
   common.Injectable()
 ], exports.MetricsService);
+
+// src/server/utils/describe-error.ts
+function describeError(cause) {
+  try {
+    if (typeof cause === "object" && cause !== null && "message" in cause) {
+      if (typeof cause.message === "string") return cause.message;
+    }
+    return String(cause);
+  } catch {
+    return "unknown error";
+  }
+}
+
+// src/server/services/worker-registry.service.ts
 var _entries;
 exports.WorkerRegistry = class WorkerRegistry {
   constructor(connection, options) {
@@ -826,7 +862,7 @@ exports.WorkerRegistry = class WorkerRegistry {
         common.HttpStatus.INTERNAL_SERVER_ERROR,
         {
           queueName,
-          cause: cause instanceof Error ? cause.message : String(cause)
+          cause: describeError(cause)
         }
       );
     }
@@ -869,7 +905,7 @@ exports.WorkerRegistry = class WorkerRegistry {
         common.HttpStatus.INTERNAL_SERVER_ERROR,
         {
           queueName,
-          cause: cause instanceof Error ? cause.message : String(cause)
+          cause: describeError(cause)
         }
       );
     }

package/dist/server/index.mjs

@@ -82,6 +82,19 @@ function invalid(reason) {
     reason
   });
 }
+function isParseableUrl(url) {
+  const candidate = /^rediss?:\/\//i.test(url) ? url : url.startsWith("//") ? `redis:${url}` : `redis://${url}`;
+  if (!URL.canParse(candidate)) return false;
+  const { username, password } = new URL(candidate);
+  let decodable = true;
+  try {
+    decodeURIComponent(username);
+    decodeURIComponent(password);
+  } catch {
+    decodable = false;
+  }
+  return decodable;
+}
 function validateOptions(opts) {
   const cfg = opts.connection;
   if (cfg === null || typeof cfg !== "object") {
@@ -96,6 +109,15 @@ function validateOptions(opts) {
   if (hasClient && (hasUrl || hasOptions)) {
     invalid("connection.client is mutually exclusive with url/options");
   }
+  if (hasUrl) {
+    const url = cfg.url;
+    if (typeof url !== "string" || url.trim() === "") {
+      invalid("connection.url must be a non-empty string");
+    }
+    if (!isParseableUrl(url)) {
+      invalid("connection.url is not a valid Redis URL");
+    }
+  }
   const drainTimeoutMs = opts.shutdown?.drainTimeoutMs;
   if (drainTimeoutMs !== void 0 && drainTimeoutMs <= 0) {
     invalid("shutdown.drainTimeoutMs must be > 0");
@@ -785,6 +807,20 @@ var MetricsService = class {
 MetricsService = __decorateClass([
   Injectable()
 ], MetricsService);
+
+// src/server/utils/describe-error.ts
+function describeError(cause) {
+  try {
+    if (typeof cause === "object" && cause !== null && "message" in cause) {
+      if (typeof cause.message === "string") return cause.message;
+    }
+    return String(cause);
+  } catch {
+    return "unknown error";
+  }
+}
+
+// src/server/services/worker-registry.service.ts
 var _entries;
 var WorkerRegistry = class {
   constructor(connection, options) {
@@ -824,7 +860,7 @@ var WorkerRegistry = class {
         HttpStatus.INTERNAL_SERVER_ERROR,
         {
           queueName,
-          cause: cause instanceof Error ? cause.message : String(cause)
+          cause: describeError(cause)
         }
       );
     }
@@ -867,7 +903,7 @@ var WorkerRegistry = class {
         HttpStatus.INTERNAL_SERVER_ERROR,
         {
           queueName,
-          cause: cause instanceof Error ? cause.message : String(cause)
+          cause: describeError(cause)
         }
       );
     }

package/package.json

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