@bymax-one/nest-queue 1.2.11 → 1.2.12

package/CHANGELOG.md

@@ -11,6 +11,34 @@ versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.2.12] — 2026-11-09
+
+No action required. The public API, the declaration files and the peer ranges are unchanged
+(`check-api-surface` reports no difference against 1.2.11); the runtime bundles (`index.mjs`,
+`index.cjs`) differ in code, measured with `diff -r` of a fresh build against the unpacked 1.2.11
+tarball. The package also ships a corrected README.
+
+### Fixed
+
+- **An outage on a connection the library opens no longer prints `[ioredis] Unhandled error event`
+  to stderr.** In Mode B the owned connection listened for `error` only while it waited for
+  `ready`, so until BullMQ built something on it (BullMQ adds its own listener to a client it is
+  handed) a later outage reached ioredis with no listener, and ioredis wrote one line per
+  reconnect attempt to raw stderr, outside the structured logger. The owned connection now keeps a
+  listener for its whole life that logs through the module's logger. The same holds for the
+  duplicate opened for each `QueueEvents` (BullMQ listens on its own copy, not on this one) and for
+  the probe the Mode A check duplicates. Every error is logged as it arrives, with no throttling.
+  A client you pass in Mode A is yours and the library adds no listener to it.
+
+### Documentation
+
+- **The README's Mode A example now compiles and runs.** It imported `CACHE_REDIS_CLIENT` from
+  `@bymax-one/nest-cache`, a name that package does not export. The example now injects
+  `ConnectionManager` and passes `cache.getClient()`, and says that `getClient()` is typed
+  `Redis | Cluster` while Mode A takes a standalone `Redis`.
+
+---
+
 ## [1.2.11] — 2026-11-06
 
 Action required only if you extend or replace `QueueLifecycle`, or rely on the order in which the
@@ -867,7 +895,8 @@ v6 peer range.
 
 ---
 
-[Unreleased]: https://github.com/bymaxone/nest-queue/compare/v1.2.11...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-queue/compare/v1.2.12...HEAD
+[1.2.12]: https://github.com/bymaxone/nest-queue/compare/v1.2.11...v1.2.12
 [1.2.11]: https://github.com/bymaxone/nest-queue/compare/v1.2.10...v1.2.11
 [1.2.10]: https://github.com/bymaxone/nest-queue/compare/v1.2.9...v1.2.10
 [1.2.9]: https://github.com/bymaxone/nest-queue/compare/v1.2.8...v1.2.9

package/README.md

@@ -270,18 +270,22 @@ Worker and QueueEvents connections are duplicated from this client with
 
 ```typescript
 import { BymaxQueueModule } from '@bymax-one/nest-queue'
-import { CACHE_REDIS_CLIENT } from '@bymax-one/nest-cache'
+import { ConnectionManager } from '@bymax-one/nest-cache'
 import type { Redis } from 'ioredis'
 
 BymaxQueueModule.forRootAsync({
-  inject: [CACHE_REDIS_CLIENT],
-  useFactory: (queueRedis: Redis) => ({
-    connection: { client: queueRedis },
+  inject: [ConnectionManager],
+  useFactory: (cache: ConnectionManager) => ({
+    connection: { client: cache.getClient() as Redis },
     isGlobal: true,
   }),
 })
 ```
 
+`BymaxCacheModule` is global by default and provides `ConnectionManager`; `getClient()` returns the shared
+client. It is typed `Redis | Cluster`, and Mode A takes a standalone `Redis`, so run
+`@bymax-one/nest-cache` in standalone mode.
+
 Mode A is the recommended setup when you already have `@bymax-one/nest-cache` in the app.
 One client is shared; the lib duplicates it per role and applies the correct retry policy
 without touching your cache connection.

package/dist/server/index.cjs

@@ -192,15 +192,46 @@ function isClientUsable(client) {
   return client.status === "ready" || client.status === "connecting";
 }
 
+// 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/utils/attach-client-error-listener.ts
+function describeClientError(err) {
+  const message = describeError(err);
+  if (message !== "") return message;
+  try {
+    const { name, code } = err;
+    const label = typeof name === "string" && name !== "" ? name : "unknown error";
+    return typeof code === "string" ? `${label} [${code}]` : label;
+  } catch {
+    return "unknown error";
+  }
+}
+function attachClientErrorListener(client, logger, role) {
+  client.on("error", (err) => {
+    logger.error(`Redis connection (${role}) emitted an error: ${describeClientError(err)}`);
+  });
+}
+
 // src/server/utils/duplicate-connection.ts
 function duplicateConnection(client) {
   return client.duplicate({ maxRetriesPerRequest: null });
 }
 
 // src/server/services/connection-resolver.service.ts
-var _client, _options;
+var _logger, _client, _options;
 exports.ConnectionResolver = class ConnectionResolver {
   constructor(options) {
+    __privateAdd(this, _logger, new common.Logger(exports.ConnectionResolver.name));
     __privateAdd(this, _client);
     __privateAdd(this, _options);
     __publicField(this, "mode");
@@ -214,6 +245,7 @@ exports.ConnectionResolver = class ConnectionResolver {
     }
     this.mode = "mode-b-owned";
     __privateSet(this, _client, "url" in cfg ? new ioredis.Redis(cfg.url, this.ownedOptions(cfg.options)) : new ioredis.Redis(this.ownedOptions(cfg.options)));
+    attachClientErrorListener(__privateGet(this, _client), __privateGet(this, _logger), "owned");
     await this.waitReady(
       __privateGet(this, _options).connectionReadyTimeoutMs ?? DEFAULT_CONNECTION_READY_TIMEOUT_MS
     );
@@ -267,6 +299,7 @@ exports.ConnectionResolver = class ConnectionResolver {
       );
     }
     const probe = duplicateConnection(client);
+    attachClientErrorListener(probe, __privateGet(this, _logger), "probe");
     try {
       assertBlockingConnection(probe);
     } finally {
@@ -305,6 +338,7 @@ exports.ConnectionResolver = class ConnectionResolver {
     });
   }
 };
+_logger = new WeakMap();
 _client = new WeakMap();
 _options = new WeakMap();
 exports.ConnectionResolver = __decorateClass([
@@ -343,18 +377,6 @@ function validateJobSchedulerOptions(repeat) {
   }
 }
 
-// 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/utils/attach-error-listener.ts
 function attachDefaultErrorListener(emitter, logger, kind, queueName) {
   emitter.on("error", (err) => {
@@ -797,6 +819,7 @@ exports.QueueEventsRegistry = class QueueEventsRegistry {
     const existing = __privateGet(this, _events).get(queueName);
     if (existing) return existing;
     const conn = duplicateConnection(this.connection.getClient());
+    attachClientErrorListener(conn, this.logger, `queue events: ${queueName}`);
     let qe;
     try {
       qe = new bullmq.QueueEvents(queueName, { connection: conn, prefix: this.options.prefix });

package/dist/server/index.mjs

@@ -1,4 +1,4 @@
-import { Injectable, Inject, ConfigurableModuleBuilder, Module, HttpStatus, Logger, HttpException } from '@nestjs/common';
+import { Injectable, Inject, ConfigurableModuleBuilder, Module, Logger, HttpStatus, HttpException } from '@nestjs/common';
 import { DiscoveryService, DiscoveryModule } from '@nestjs/core';
 import { Redis } from 'ioredis';
 import { Worker, QueueEvents, Queue, FlowProducer, defaultRepeatStrategy } from 'bullmq';
@@ -190,15 +190,46 @@ function isClientUsable(client) {
   return client.status === "ready" || client.status === "connecting";
 }
 
+// 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/utils/attach-client-error-listener.ts
+function describeClientError(err) {
+  const message = describeError(err);
+  if (message !== "") return message;
+  try {
+    const { name, code } = err;
+    const label = typeof name === "string" && name !== "" ? name : "unknown error";
+    return typeof code === "string" ? `${label} [${code}]` : label;
+  } catch {
+    return "unknown error";
+  }
+}
+function attachClientErrorListener(client, logger, role) {
+  client.on("error", (err) => {
+    logger.error(`Redis connection (${role}) emitted an error: ${describeClientError(err)}`);
+  });
+}
+
 // src/server/utils/duplicate-connection.ts
 function duplicateConnection(client) {
   return client.duplicate({ maxRetriesPerRequest: null });
 }
 
 // src/server/services/connection-resolver.service.ts
-var _client, _options;
+var _logger, _client, _options;
 var ConnectionResolver = class {
   constructor(options) {
+    __privateAdd(this, _logger, new Logger(ConnectionResolver.name));
     __privateAdd(this, _client);
     __privateAdd(this, _options);
     __publicField(this, "mode");
@@ -212,6 +243,7 @@ var ConnectionResolver = class {
     }
     this.mode = "mode-b-owned";
     __privateSet(this, _client, "url" in cfg ? new Redis(cfg.url, this.ownedOptions(cfg.options)) : new Redis(this.ownedOptions(cfg.options)));
+    attachClientErrorListener(__privateGet(this, _client), __privateGet(this, _logger), "owned");
     await this.waitReady(
       __privateGet(this, _options).connectionReadyTimeoutMs ?? DEFAULT_CONNECTION_READY_TIMEOUT_MS
     );
@@ -265,6 +297,7 @@ var ConnectionResolver = class {
       );
     }
     const probe = duplicateConnection(client);
+    attachClientErrorListener(probe, __privateGet(this, _logger), "probe");
     try {
       assertBlockingConnection(probe);
     } finally {
@@ -303,6 +336,7 @@ var ConnectionResolver = class {
     });
   }
 };
+_logger = new WeakMap();
 _client = new WeakMap();
 _options = new WeakMap();
 ConnectionResolver = __decorateClass([
@@ -341,18 +375,6 @@ function validateJobSchedulerOptions(repeat) {
   }
 }
 
-// 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/utils/attach-error-listener.ts
 function attachDefaultErrorListener(emitter, logger, kind, queueName) {
   emitter.on("error", (err) => {
@@ -795,6 +817,7 @@ var QueueEventsRegistry = class {
     const existing = __privateGet(this, _events).get(queueName);
     if (existing) return existing;
     const conn = duplicateConnection(this.connection.getClient());
+    attachClientErrorListener(conn, this.logger, `queue events: ${queueName}`);
     let qe;
     try {
       qe = new QueueEvents(queueName, { connection: conn, prefix: this.options.prefix });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-queue",
-  "version": "1.2.11",
+  "version": "1.2.12",
   "description": "NestJS dynamic module wrapping BullMQ — typed jobs, flows, job schedulers, deduplication, OpenTelemetry, graceful shutdown",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -58,10 +58,12 @@
     "check:api": "node scripts/check-api-surface.mjs",
     "check:exports": "attw --pack .",
     "check:mutants": "node scripts/check-mutation-directives.mjs",
+    "check:file-length": "node scripts/check-file-length.mjs",
     "check:published": "node scripts/check-published-surface.mjs",
     "clean": "rm -rf dist coverage",
     "lint": "eslint src scripts test",
     "lint:fix": "eslint src scripts test --fix",
+    "mutation:const-tables": "node scripts/mutate-const-tables.mjs -- pnpm exec jest --config jest.mutants.config.ts --findRelatedTests {file} --coverage=false --silent",
     "mutation": "stryker run",
     "mutation:full": "node -e \"require('node:fs').rmSync('reports/stryker-incremental.json',{force:true,recursive:true})\" && stryker run",
     "mutation:dry-run": "stryker run --dryRunOnly",
@@ -95,6 +97,7 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
+    "@bymax-one/nest-cache": "1.2.8",
     "@commitlint/cli": "^21.2.1",
     "@commitlint/config-conventional": "^21.2.0",
     "@eslint/js": "^10.0.1",