@bymax-one/nest-queue 1.2.5 → 1.2.7

package/CHANGELOG.md

@@ -11,6 +11,56 @@ versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [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.
+Measured with `diff -r` of a fresh build against the unpacked 1.2.5 tarball, `dist/` is identical;
+the package otherwise changes in `README.md`, this file and the version in `package.json`.
+
+### Documentation
+
+- **The README Quick Start now shows where `EmailService` and the processor are registered.** The
+  `AppModule` snippet imports an `EmailModule` that lists both as providers, so a reader who copies
+  the snippets in order ends with a module graph that resolves, instead of a service no module provides
+  and a processor module the root never imports.
+
+### Tests
+
+- **The README Quick Start now runs.** A spec boots a Nest application context from the module
+  options, the `QueueService` enqueue and the `@Processor` / `@Process` handler copied from the
+  README (handler body aside), with BullMQ and ioredis replaced by in-memory doubles, and asserts
+  the job the service enqueues is the job the decorated handler receives. The snippet gate only
+  compiles the README; this executes it, so a wrong argument shape or an unresolved dependency fails
+  a test.
+
+---
+
 ## [1.2.5] — 2026-10-31
 
 No action required: behaviour, the public API, the types and the peer ranges are unchanged.
@@ -678,7 +728,9 @@ v6 peer range.
 
 ---
 
-[Unreleased]: https://github.com/bymaxone/nest-queue/compare/v1.2.5...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-queue/compare/v1.2.7...HEAD
+[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
 [1.2.3]: https://github.com/bymaxone/nest-queue/compare/v1.2.2...v1.2.3

package/README.md

@@ -168,6 +168,7 @@ Wire the module in your root `AppModule`:
 ```typescript
 import { Module } from '@nestjs/common'
 import { BymaxQueueModule } from '@bymax-one/nest-queue'
+import { EmailModule } from './email.module'
 
 @Module({
   imports: [
@@ -175,6 +176,7 @@ import { BymaxQueueModule } from '@bymax-one/nest-queue'
       connection: { url: process.env.REDIS_URL ?? 'redis://localhost:6379' },
       isGlobal: true,
     }),
+    EmailModule,
   ],
 })
 export class AppModule {}
@@ -213,14 +215,16 @@ export class EmailProcessor {
 }
 ```
 
-Register the processor in your module alongside `BymaxQueueModule`:
+Register the service and the processor in a feature module that `AppModule` imports, like the `EmailModule`
+imported above. `isGlobal: true` above makes `QueueService` injectable there without importing `BymaxQueueModule` again:
 
 ```typescript
 import { Module } from '@nestjs/common'
 import { EmailProcessor } from './email.processor'
+import { EmailService } from './email.service'
 
 @Module({
-  providers: [EmailProcessor],
+  providers: [EmailService, EmailProcessor],
 })
 export class EmailModule {}
 ```

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.5",
+  "version": "1.2.7",
   "description": "NestJS dynamic module wrapping BullMQ — typed jobs, flows, job schedulers, deduplication, OpenTelemetry, graceful shutdown",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",