@bymax-one/nest-cache 1.0.5 → 1.1.0

package/CHANGELOG.md

@@ -4,7 +4,47 @@ All notable changes to this project are documented in this file. The format is
 based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.1.0] - 2026-08-11
+
+### Changed
+
+- **BREAKING: peer dependency `ioredis` migrated `^5` → `^6`.** A consumer must move to
+  ioredis 6, which aligns this package with `@bymax-one/nest-queue` so a single ioredis copy
+  resolves across a workspace that uses both. ioredis 6 negotiates **RESP3** on the wire by
+  default — the protocol changes at runtime — but its `'legacy'` reply mapping preserves every
+  reply shape this cache relies on (GET/SET/TTL, EVALSHA, Pub/Sub message events, cluster and
+  sentinel commands), so observable behaviour is unchanged; the only source change is the
+  compile-time typing narrowing below. ioredis 6 requires Node.js ≥ 20, already covered by
+  this package's `engines` (Node ≥ 24).
+
+### Internal
+
+- `ConnectionManager` narrows the options handed to the `Redis` and `Cluster` constructors
+  to a local shape (`OwnedRedisOptions` / `OwnedClusterOptions`). ioredis 6's constructor
+  overloads intersect `replyMapping` with a non-`undefined` variant to infer the
+  reply-mapping generic, which makes a plain `RedisOptions`/`ClusterOptions` value
+  unassignable under `exactOptionalPropertyTypes`. The narrowing drops only that `undefined`;
+  the runtime object is untouched.
+- Mutation gate tightened: Stryker `break`/`high`/`low` raised to **100** (the run is at
+  100%, 0 survivors).
+
+## [1.0.6] - 2026-08-06
+
+### Fixed
+
+- `ConnectionManager.onModuleInit()` assigned a freshly created client over the field
+  unconditionally. When something had already opened the main client through
+  `getClient()`, that first socket was left connected with no reference left to close it —
+  `onModuleDestroy()` quits only the current client, so the abandoned one stayed in Redis's
+  `CLIENT LIST` until its own timeout. Init now adopts an existing client instead of
+  replacing it, and the assignment lives in one private accessor so no other path can
+  strand a live connection.
+
+  Reaching it takes touching the cache before the cache module's own init hook runs, which
+  is possible in two ordinary shapes: NestJS orders `onModuleInit` by module depth, so a
+  consumer module deeper in the graph runs first, and `app.get()` works between
+  `NestFactory.create()` and `app.init()`. The ordinary boot path opened exactly one client
+  before this change and still does.
 
 ## [1.0.5] - 2026-08-06
 
@@ -150,6 +190,8 @@ type or export moved.
 - Published with npm OIDC provenance — no long-lived tokens
 - Zero direct runtime dependencies (`dependencies: {}`) — `ioredis` and NestJS via peer deps
 
+[1.1.0]: https://github.com/bymaxone/nest-cache/compare/v1.0.6...v1.1.0
+[1.0.6]: https://github.com/bymaxone/nest-cache/compare/v1.0.5...v1.0.6
 [1.0.5]: https://github.com/bymaxone/nest-cache/compare/v1.0.4...v1.0.5
 [1.0.4]: https://github.com/bymaxone/nest-cache/compare/v1.0.3...v1.0.4
 [1.0.3]: https://github.com/bymaxone/nest-cache/releases/tag/v1.0.3

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <strong>Typed Redis cache for NestJS</strong><br />
-  <sub>ioredis 5 · Namespacing · Pub/Sub · Lua Scripts · Multi-Tenant · Zero Runtime Dependencies</sub>
+  <sub>ioredis 6 · Namespacing · Pub/Sub · Lua Scripts · Multi-Tenant · Zero Runtime Dependencies</sub>
 </p>
 
 <p align="center">
@@ -14,7 +14,7 @@
   <a href="https://www.npmjs.com/package/@bymax-one/nest-cache"><img src="https://img.shields.io/npm/dm/@bymax-one/nest-cache?style=flat-square&colorA=000000&colorB=000000" alt="npm downloads" /></a>
   <a href="https://github.com/bymaxone/nest-cache/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/bymaxone/nest-cache/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI" alt="CI status" /></a>
   <a href="https://github.com/bymaxone/nest-cache/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000" alt="coverage" /></a>
-  <a href="https://github.com/bymaxone/nest-cache/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-99.78%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
+  <a href="https://github.com/bymaxone/nest-cache/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-100%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/bymaxone/nest-cache"><img src="https://api.scorecard.dev/projects/github.com/bymaxone/nest-cache/badge?style=flat-square" alt="OpenSSF Scorecard" /></a>
   <a href="https://github.com/bymaxone/nest-cache/blob/main/LICENSE"><img src="https://img.shields.io/github/license/bymaxone/nest-cache?style=flat-square&colorA=000000&colorB=000000" alt="license" /></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /></a>
@@ -101,7 +101,7 @@ One package, two entry points — import only what your app needs:
 
 | Subpath    | Import                         | Purpose                                                                                                  |              Dependencies              |
 | ---------- | ------------------------------ | -------------------------------------------------------------------------------------------------------- | :------------------------------------: |
-| **Server** | `@bymax-one/nest-cache`        | `BymaxCacheModule`, `CacheService`, `PubSubService`, `ScriptManagerService`, DI tokens, `CacheException` | NestJS 11, ioredis 5, reflect-metadata |
+| **Server** | `@bymax-one/nest-cache`        | `BymaxCacheModule`, `CacheService`, `PubSubService`, `ScriptManagerService`, DI tokens, `CacheException` | NestJS 11, ioredis 6, reflect-metadata |
 | **Shared** | `@bymax-one/nest-cache/shared` | Types + constants — `CACHE_ERROR_CODES`, `CacheEventName`, config types                                  |                  None                  |
 
 ```
@@ -511,7 +511,7 @@ When integrating `@bymax-one/nest-cache` in production, verify each of the follo
 ## 🧱 Tech Stack
 
 [![NestJS](https://img.shields.io/badge/NestJS-11-E0234E?style=flat-square&logo=nestjs&logoColor=white)](https://nestjs.com)
-[![ioredis](https://img.shields.io/badge/ioredis-5-DC382D?style=flat-square&logo=redis&logoColor=white)](https://github.com/redis/ioredis)
+[![ioredis](https://img.shields.io/badge/ioredis-6-DC382D?style=flat-square&logo=redis&logoColor=white)](https://github.com/redis/ioredis)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
 [![Node.js](https://img.shields.io/badge/Node.js-24-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
 [![Jest](https://img.shields.io/badge/Jest-30-C21325?style=flat-square&logo=jest)](https://jestjs.io)
@@ -526,8 +526,8 @@ When integrating `@bymax-one/nest-cache` in production, verify each of the follo
 A cache is consulted on the hot path of every request that touches it, so the suite is held to a bar beyond "it runs" — every behavior is pinned so that a regression **fails a test**.
 
 - ✅ **100% line coverage** — statements, branches, functions, and lines, enforced by `jest.coverage.config.ts` as a pre-publish gate, not a target
-- ✅ **99.78% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at `break: 95` and `ignoreStatic: false`; the single survivor is `configurable: false` on the withheld connection accessor, equivalent here because the resolved options are frozen on the way out, and [documented as such](./docs/mutation_testing_results.md)
-- ✅ **Zero suppressions** — the production source carries no coverage or mutation directives; the one would-be equivalent mutant was refactored away rather than silenced, so the score is an accounting rather than a number
+- ✅ **100% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at `break: 100` and `ignoreStatic: false`; 441 killed, 6 timed out, **0 survived**, and [documented in full](./docs/mutation_testing_results.md)
+- ✅ **One documented equivalent** — the production source carries a single `// Stryker disable` directive, on `configurable: false` of the withheld connection accessor, genuinely equivalent because the resolved options are frozen on the way out (freezing already makes every property non-configurable); `check:mutants` proves it parses and carries its reason, so the score is an accounting rather than a number
 - ✅ **No real Redis in unit tests** — `ioredis-mock` throughout; e2e tests exercise the wired module through `@nestjs/testing` and Testcontainers against a real Redis for connection lifecycle, Pub/Sub, and Lua scripts
 - ✅ **Published-package smoke test** — `scripts/dogfood-smoke-test.mjs` validates exports, tarball shape, and a consumer install before tagging
 

package/dist/server/index.cjs

@@ -227,6 +227,7 @@ function applyDefaults(options) {
     Object.defineProperty(resolved, key, {
       get: () => value,
       enumerable: false,
+      // Stryker disable next-line BooleanLiteral: equivalent HERE — `resolved` is `Object.freeze`d on the way out and freezing makes every property non-configurable anyway, so flipping this flag changes nothing observable. It stays because it states the guarantee where the accessor is defined, and nest-storage withholds its credentials the same way WITHOUT freezing, where this flag is the only thing enforcing it.
       configurable: false
     });
   }
@@ -259,12 +260,19 @@ exports.ConnectionManager = class ConnectionManager {
     this.defaultReconnectOnError = (err) => err.message.includes("READONLY");
     __privateSet(this, _redisOptionsResolved, this.buildRedisOptions(options));
   }
-  /** Opens the main client and waits for readiness unless `lazyConnect`. */
+  /**
+   * Opens the main client and waits for readiness unless `lazyConnect`.
+   *
+   * Adopts a client {@link getClient} already opened rather than replacing it:
+   * NestJS orders `onModuleInit` by module depth, and `app.get()` works before
+   * `app.init()`, so a consumer can reach the cache first. Overwriting here
+   * would strand that socket with no reference left to close it — teardown
+   * quits only the current client.
+   */
   async onModuleInit() {
-    __privateSet(this, _client, this.createClient());
-    this.registerListeners(__privateGet(this, _client), "main");
+    const client = this.ensureClient();
     if (!this.options.connection?.lazyConnect) {
-      await this.waitUntilReady(__privateGet(this, _client));
+      await this.waitUntilReady(client);
     }
   }
   /**
@@ -274,11 +282,7 @@ exports.ConnectionManager = class ConnectionManager {
    * @returns The shared main client.
    */
   getClient() {
-    if (!__privateGet(this, _client)) {
-      __privateSet(this, _client, this.createClient());
-      this.registerListeners(__privateGet(this, _client), "main");
-    }
-    return __privateGet(this, _client);
+    return this.ensureClient();
   }
   /**
    * Creates a brand-new dedicated connection for subscriber mode (a subscriber
@@ -336,6 +340,20 @@ exports.ConnectionManager = class ConnectionManager {
     }
   }
   // ─── Private ──────────────────────────────────────────────────────────────
+  /**
+   * Returns the main client, opening and wiring it on the first call. The only
+   * place a live client is assigned, so no caller can replace one; teardown
+   * only clears the field back to `null`.
+   *
+   * @returns The shared main client.
+   */
+  ensureClient() {
+    if (!__privateGet(this, _client)) {
+      __privateSet(this, _client, this.createClient());
+      this.registerListeners(__privateGet(this, _client), "main");
+    }
+    return __privateGet(this, _client);
+  }
   /**
    * Instantiates the client matching the configured mode.
    *
@@ -358,7 +376,7 @@ exports.ConnectionManager = class ConnectionManager {
           sentinelPassword: sentinel.sentinelPassword
         },
         ...sentinel.password !== void 0 && { password: sentinel.password },
-        // Normalize 'replica' → 'slave' — ioredis 5 only accepts 'slave' at the
+        // Normalize 'replica' → 'slave' — ioredis only accepts 'slave' at the
         // wire level; our public interface accepts 'replica' per Redis 7 naming.
         ...sentinel.role !== void 0 && {
           role: sentinel.role === "replica" ? "slave" : sentinel.role

package/dist/server/index.d.cts

@@ -369,7 +369,15 @@ declare class ConnectionManager implements OnModuleInit, OnModuleDestroy {
      *   module can provide `null` when the consumer omits `events`.
      */
     constructor(options: ResolvedOptions, events?: ICacheEvents | undefined);
-    /** Opens the main client and waits for readiness unless `lazyConnect`. */
+    /**
+     * Opens the main client and waits for readiness unless `lazyConnect`.
+     *
+     * Adopts a client {@link getClient} already opened rather than replacing it:
+     * NestJS orders `onModuleInit` by module depth, and `app.get()` works before
+     * `app.init()`, so a consumer can reach the cache first. Overwriting here
+     * would strand that socket with no reference left to close it — teardown
+     * quits only the current client.
+     */
     onModuleInit(): Promise<void>;
     /**
      * Returns the singleton main client, creating it on first access if the
@@ -398,6 +406,14 @@ declare class ConnectionManager implements OnModuleInit, OnModuleDestroy {
     createSubscriberClient(): AnyRedis;
     /** Quits the main client gracefully, forcing `disconnect()` on timeout. */
     onModuleDestroy(): Promise<void>;
+    /**
+     * Returns the main client, opening and wiring it on the first call. The only
+     * place a live client is assigned, so no caller can replace one; teardown
+     * only clears the field back to `null`.
+     *
+     * @returns The shared main client.
+     */
+    private ensureClient;
     /**
      * Instantiates the client matching the configured mode.
      *

package/dist/server/index.d.ts

@@ -369,7 +369,15 @@ declare class ConnectionManager implements OnModuleInit, OnModuleDestroy {
      *   module can provide `null` when the consumer omits `events`.
      */
     constructor(options: ResolvedOptions, events?: ICacheEvents | undefined);
-    /** Opens the main client and waits for readiness unless `lazyConnect`. */
+    /**
+     * Opens the main client and waits for readiness unless `lazyConnect`.
+     *
+     * Adopts a client {@link getClient} already opened rather than replacing it:
+     * NestJS orders `onModuleInit` by module depth, and `app.get()` works before
+     * `app.init()`, so a consumer can reach the cache first. Overwriting here
+     * would strand that socket with no reference left to close it — teardown
+     * quits only the current client.
+     */
     onModuleInit(): Promise<void>;
     /**
      * Returns the singleton main client, creating it on first access if the
@@ -398,6 +406,14 @@ declare class ConnectionManager implements OnModuleInit, OnModuleDestroy {
     createSubscriberClient(): AnyRedis;
     /** Quits the main client gracefully, forcing `disconnect()` on timeout. */
     onModuleDestroy(): Promise<void>;
+    /**
+     * Returns the main client, opening and wiring it on the first call. The only
+     * place a live client is assigned, so no caller can replace one; teardown
+     * only clears the field back to `null`.
+     *
+     * @returns The shared main client.
+     */
+    private ensureClient;
     /**
      * Instantiates the client matching the configured mode.
      *

package/dist/server/index.mjs

@@ -225,6 +225,7 @@ function applyDefaults(options) {
     Object.defineProperty(resolved, key, {
       get: () => value,
       enumerable: false,
+      // Stryker disable next-line BooleanLiteral: equivalent HERE — `resolved` is `Object.freeze`d on the way out and freezing makes every property non-configurable anyway, so flipping this flag changes nothing observable. It stays because it states the guarantee where the accessor is defined, and nest-storage withholds its credentials the same way WITHOUT freezing, where this flag is the only thing enforcing it.
       configurable: false
     });
   }
@@ -257,12 +258,19 @@ var ConnectionManager = class {
     this.defaultReconnectOnError = (err) => err.message.includes("READONLY");
     __privateSet(this, _redisOptionsResolved, this.buildRedisOptions(options));
   }
-  /** Opens the main client and waits for readiness unless `lazyConnect`. */
+  /**
+   * Opens the main client and waits for readiness unless `lazyConnect`.
+   *
+   * Adopts a client {@link getClient} already opened rather than replacing it:
+   * NestJS orders `onModuleInit` by module depth, and `app.get()` works before
+   * `app.init()`, so a consumer can reach the cache first. Overwriting here
+   * would strand that socket with no reference left to close it — teardown
+   * quits only the current client.
+   */
   async onModuleInit() {
-    __privateSet(this, _client, this.createClient());
-    this.registerListeners(__privateGet(this, _client), "main");
+    const client = this.ensureClient();
     if (!this.options.connection?.lazyConnect) {
-      await this.waitUntilReady(__privateGet(this, _client));
+      await this.waitUntilReady(client);
     }
   }
   /**
@@ -272,11 +280,7 @@ var ConnectionManager = class {
    * @returns The shared main client.
    */
   getClient() {
-    if (!__privateGet(this, _client)) {
-      __privateSet(this, _client, this.createClient());
-      this.registerListeners(__privateGet(this, _client), "main");
-    }
-    return __privateGet(this, _client);
+    return this.ensureClient();
   }
   /**
    * Creates a brand-new dedicated connection for subscriber mode (a subscriber
@@ -334,6 +338,20 @@ var ConnectionManager = class {
     }
   }
   // ─── Private ──────────────────────────────────────────────────────────────
+  /**
+   * Returns the main client, opening and wiring it on the first call. The only
+   * place a live client is assigned, so no caller can replace one; teardown
+   * only clears the field back to `null`.
+   *
+   * @returns The shared main client.
+   */
+  ensureClient() {
+    if (!__privateGet(this, _client)) {
+      __privateSet(this, _client, this.createClient());
+      this.registerListeners(__privateGet(this, _client), "main");
+    }
+    return __privateGet(this, _client);
+  }
   /**
    * Instantiates the client matching the configured mode.
    *
@@ -356,7 +374,7 @@ var ConnectionManager = class {
           sentinelPassword: sentinel.sentinelPassword
         },
         ...sentinel.password !== void 0 && { password: sentinel.password },
-        // Normalize 'replica' → 'slave' — ioredis 5 only accepts 'slave' at the
+        // Normalize 'replica' → 'slave' — ioredis only accepts 'slave' at the
         // wire level; our public interface accepts 'replica' per Redis 7 naming.
         ...sentinel.role !== void 0 && {
           role: sentinel.role === "replica" ? "slave" : sentinel.role

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bymax-one/nest-cache",
-  "version": "1.0.5",
-  "description": "Typed Redis cache for NestJS based on ioredis 5, with namespace strategy, Pub/Sub and Lua script management.",
+  "version": "1.1.0",
+  "description": "Typed Redis cache for NestJS based on ioredis 6, with namespace strategy, Pub/Sub and Lua script management.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
   "homepage": "https://github.com/bymaxone/nest-cache#readme",
@@ -56,15 +56,16 @@
   "scripts": {
     "build": "pnpm clean && tsup",
     "check:exports": "attw --pack .",
+    "check:mutants": "node scripts/check-mutation-directives.mjs",
     "check:published": "node scripts/check-published-surface.mjs",
     "clean": "rm -rf dist coverage",
     "lint": "eslint src scripts",
     "lint:fix": "eslint src scripts --fix",
     "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",
-    "mutation:incremental": "stryker run --incremental",
     "prepare": "husky",
-    "prepublishOnly": "pnpm clean && pnpm typecheck && pnpm test:types && pnpm lint && pnpm test:cov:all && pnpm build && pnpm check:published",
+    "prepublishOnly": "pnpm clean && pnpm typecheck && pnpm test:types && pnpm lint && pnpm check:mutants && pnpm test:cov:all && pnpm build && pnpm check:published",
     "release": "npm publish --provenance --access public",
     "size": "node scripts/check-size.mjs",
     "test": "jest",
@@ -89,7 +90,7 @@
   "peerDependencies": {
     "@nestjs/common": "^11.0.16",
     "@nestjs/core": "^11.1.18",
-    "ioredis": "^5.0.0",
+    "ioredis": "^6.0.0",
     "reflect-metadata": "^0.2.0"
   },
   "devDependencies": {
@@ -115,7 +116,7 @@
     "eslint-plugin-security": "^4.0.0",
     "globals": "^17.6.0",
     "husky": "^9.1.7",
-    "ioredis": "^5.10.1",
+    "ioredis": "^6.0.0",
     "ioredis-mock": "^8.13.1",
     "jest": "^30.4.2",
     "lint-staged": "^17.2.0",