@bymax-one/nest-cache 1.2.4 → 1.2.6

package/CHANGELOG.md

@@ -6,6 +6,42 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [1.2.6] - 2026-10-31
+
+### Added
+
+- **`createConnectionManager(options)`**, exported from the main entry. It takes the options
+  `BymaxCacheModule.forRoot` takes, validates and defaults them exactly as the module does, and returns a
+  `ConnectionManager` that Nest connects on `onModuleInit` and quits on `onModuleDestroy` when it is
+  registered as a provider. A consumer that needs a second, dedicated connection (for example a standalone
+  one beside a clustered cache) no longer has to hand-write `ResolvedOptions`, which skipped validation and
+  the defaults. The README has a section, "A second, dedicated connection", with a provider snippet.
+
+### Internal
+
+- `forRoot`, `forRootAsync` and `createConnectionManager` share one `resolveOptions` function, so the
+  sequence "validate, then apply defaults" is written once. Nothing about `forRoot` or `forRootAsync`
+  changes.
+
+## [1.2.5] - 2026-10-31
+
+A documentation and test release. Nothing you execute changes: `dist/` differs from 1.2.4 only in one comment, the
+JSDoc of `ConnectionManager.createSubscriberClient`, which no longer calls cluster Pub/Sub experimental.
+
+### Documentation
+
+- The README states that Pub/Sub works in cluster mode: channel and pattern subscribers both receive the
+  message. The same sentence in the `createSubscriberClient` JSDoc described it as an experimental
+  passthrough.
+
+### Tests
+
+- The cluster end-to-end suite runs three masters on `redis:8-alpine`, formed with `redis-cli --cluster
+create`, and measures what the cluster guards claim: `keys`, `getClient`, `scan`, `flushNamespace` and the
+  administration calls that read keys throw `UNSUPPORTED_IN_CLUSTER`, a rejected `ttlSeconds` writes nothing,
+  and Pub/Sub delivers to channel and pattern subscribers. Without the `keys` guard a real cluster returned
+  2 of 6 seeded keys.
+
 ## [1.2.4] - 2026-10-31
 
 Two calls now refuse input they could not honor, one error code is added, and the documentation catches up with the code.
@@ -460,7 +496,9 @@ type or export moved.
 - Published with npm OIDC provenance — no long-lived tokens
 - Zero direct runtime dependencies (`dependencies: {}`) — `ioredis` and NestJS via peer deps
 
-[Unreleased]: https://github.com/bymaxone/nest-cache/compare/v1.2.4...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-cache/compare/v1.2.6...HEAD
+[1.2.6]: https://github.com/bymaxone/nest-cache/compare/v1.2.5...v1.2.6
+[1.2.5]: https://github.com/bymaxone/nest-cache/compare/v1.2.4...v1.2.5
 [1.2.4]: https://github.com/bymaxone/nest-cache/compare/v1.2.3...v1.2.4
 [1.2.3]: https://github.com/bymaxone/nest-cache/compare/v1.2.2...v1.2.3
 [1.2.2]: https://github.com/bymaxone/nest-cache/compare/v1.2.1...v1.2.2

package/README.md

@@ -279,6 +279,45 @@ Both `forRoot(options)` (synchronous) and `forRootAsync({ useFactory, inject, im
 
 ---
 
+## 🔌 A second, dedicated connection
+
+`BymaxCacheModule` registers one connection. When another part of the application needs its own, with different options (for example a standalone connection beside a cache that runs in cluster mode), build it with `createConnectionManager` rather than hand-writing the resolved options, which would skip validation and the defaults.
+
+```ts
+import { Inject, Injectable, Module } from '@nestjs/common'
+import { ConnectionManager, createConnectionManager } from '@bymax-one/nest-cache'
+
+export const AUTH_REDIS = Symbol('AUTH_REDIS')
+
+@Module({
+  providers: [
+    {
+      provide: AUTH_REDIS,
+      useFactory: (): ConnectionManager =>
+        createConnectionManager({
+          mode: 'standalone',
+          connection: { url: process.env.AUTH_REDIS_URL ?? 'redis://localhost:6379' }
+        })
+    }
+  ],
+  exports: [AUTH_REDIS]
+})
+export class AuthRedisModule {}
+
+@Injectable()
+export class SessionStore {
+  constructor(@Inject(AUTH_REDIS) private readonly redis: ConnectionManager) {}
+
+  async ping(): Promise<string> {
+    return this.redis.getClient().ping()
+  }
+}
+```
+
+It takes the same options as `forRoot()` and runs the same validation and defaults, so an invalid set throws the same `CacheException` before any client exists. The manager owns its connection: Nest connects it on `onModuleInit` and quits it on `onModuleDestroy`, with the forced `disconnect()` after `shutdownTimeoutMs`, so you write neither hook. The connection is independent of the one the module registers, and the client you get from `getClient()` applies no namespace: its keys are not prefixed.
+
+---
+
 ## 🔑 Key Namespacing
 
 Every key is composed as `{namespace}{separator}{prefix}{separator}{id}` (default separator `:`).
@@ -324,6 +363,9 @@ Channels are namespaced like keys. The subscriber connection is created lazily o
 subscription. Redis Pub/Sub is fire-and-forget — messages published while a subscriber is offline
 are not replayed.
 
+Pub/Sub also works in cluster mode: channel and pattern subscribers both receive the message, which
+the end-to-end suite verifies against a three-master cluster.
+
 ---
 
 ## 📜 Lua Scripts

package/dist/server/index.cjs

@@ -290,6 +290,10 @@ function applyDefaults(options) {
   }
   return Object.freeze(resolved);
 }
+function resolveOptions(options) {
+  validateOptions(options);
+  return applyDefaults(options);
+}
 var _client, _redisOptionsResolved;
 exports.ConnectionManager = class ConnectionManager {
   /**
@@ -354,7 +358,8 @@ exports.ConnectionManager = class ConnectionManager {
    * ready buffers until connected instead of failing fast like the data-plane
    * main client (whose offline queue stays disabled to avoid silent buffering).
    * This override applies to standalone/sentinel modes only; in cluster mode
-   * {@link createClient} ignores it (cluster Pub/Sub is an experimental passthrough).
+   * {@link createClient} ignores it and the cluster client manages its own subscriber
+   * connection.
    *
    * @returns A fresh client wired with `subscriber`-role event listeners.
    */
@@ -1646,8 +1651,7 @@ exports.BymaxCacheModule = class BymaxCacheModule extends ConfigurableModuleClas
    *   fail bootstrap validation (e.g. missing connection, misconfigured mode).
    */
   static forRoot(options) {
-    validateOptions(options);
-    const resolved = applyDefaults(options);
+    const resolved = resolveOptions(options);
     const providers = [
       { provide: MODULE_OPTIONS_TOKEN, useValue: options },
       { provide: BYMAX_CACHE_OPTIONS, useValue: resolved },
@@ -1704,10 +1708,7 @@ exports.BymaxCacheModule = class BymaxCacheModule extends ConfigurableModuleClas
     return [
       {
         provide: BYMAX_CACHE_OPTIONS,
-        useFactory: (raw) => {
-          validateOptions(raw);
-          return applyDefaults(raw);
-        },
+        useFactory: (raw) => resolveOptions(raw),
         inject: [MODULE_OPTIONS_TOKEN]
       },
       {
@@ -1772,6 +1773,12 @@ exports.BymaxCacheModule = __decorateClass([
   common.Module({})
 ], exports.BymaxCacheModule);
 
+// src/server/connection/create-connection-manager.ts
+function createConnectionManager(options) {
+  const resolved = resolveOptions(options);
+  return new exports.ConnectionManager(resolved, resolved.events);
+}
+
 // src/shared/constants/event-names.ts
 var CACHE_EVENT_NAMES = {
   CONNECT: "connect",
@@ -1795,3 +1802,4 @@ exports.CacheException = CacheException;
 exports.DEFAULT_KEY_SEPARATOR = DEFAULT_KEY_SEPARATOR;
 exports.DEFAULT_NAMESPACE = DEFAULT_NAMESPACE;
 exports.DEFAULT_REDIS_PORT = DEFAULT_REDIS_PORT;
+exports.createConnectionManager = createConnectionManager;

package/dist/server/index.d.cts

@@ -399,7 +399,8 @@ declare class ConnectionManager implements OnModuleInit, OnModuleDestroy {
      * ready buffers until connected instead of failing fast like the data-plane
      * main client (whose offline queue stays disabled to avoid silent buffering).
      * This override applies to standalone/sentinel modes only; in cluster mode
-     * {@link createClient} ignores it (cluster Pub/Sub is an experimental passthrough).
+     * {@link createClient} ignores it and the cluster client manages its own subscriber
+     * connection.
      *
      * @returns A fresh client wired with `subscriber`-role event listeners.
      */
@@ -432,6 +433,48 @@ declare class ConnectionManager implements OnModuleInit, OnModuleDestroy {
     private waitUntilReady;
 }
 
+/**
+ * Factory for a dedicated, lifecycle-managed Redis connection.
+ *
+ * Layer: server. A consumer that needs a second connection with its own options (for
+ * example a standalone one beside a clustered cache) builds it here instead of
+ * hand-writing the resolved options, which would skip validation and the defaults.
+ */
+
+/**
+ * Builds a {@link ConnectionManager} from the same options `BymaxCacheModule.forRoot`
+ * takes: the options are validated and defaulted exactly as the module does, so an invalid
+ * set throws the same `CacheException` before any client exists.
+ *
+ * The manager owns its connection. Register it as a provider and Nest connects it on
+ * `onModuleInit` and quits it on `onModuleDestroy`, with the forced `disconnect()` after
+ * `shutdownTimeoutMs`; the caller writes neither hook. Reach the client with
+ * `manager.getClient()`. This connection is independent of the one `BymaxCacheModule`
+ * registers, and it applies no namespace: keys written through its client are not
+ * prefixed.
+ *
+ * @param options - The connection options, as for `BymaxCacheModule.forRoot`.
+ * @returns A new manager that has not connected yet.
+ * @throws {CacheException} `SENTINEL_MISCONFIGURED`, `CLUSTER_MISCONFIGURED`,
+ *   `CONNECTION_FAILED` or `INVALID_NAMESPACE` when the options are invalid.
+ * @example
+ * ```ts
+ * export const AUTH_REDIS = Symbol('AUTH_REDIS')
+ *
+ * @Module({
+ *   providers: [
+ *     {
+ *       provide: AUTH_REDIS,
+ *       useFactory: () => createConnectionManager({ connection: { url: 'redis://localhost:6379' } })
+ *     }
+ *   ],
+ *   exports: [AUTH_REDIS]
+ * })
+ * export class AuthRedisModule {}
+ * ```
+ */
+declare function createConnectionManager(options: BymaxCacheModuleOptions): ConnectionManager;
+
 /**
  * Composes Redis keys following `{namespace}{separator}{prefix}{separator}{id}`.
  *
@@ -1343,4 +1386,4 @@ declare const CACHE_EVENT_NAMES: {
     readonly END: "end";
 };
 
-export { BYMAX_CACHE_CONNECTION, BYMAX_CACHE_EVENTS, BYMAX_CACHE_KEY_BUILDER, BYMAX_CACHE_OPTIONS, BYMAX_CACHE_SCRIPT_REGISTRY, BYMAX_CACHE_SERIALIZER, type BymaxCacheClusterConnection, BymaxCacheModule, type BymaxCacheModuleAsyncOptions, type BymaxCacheModuleOptions, type BymaxCacheSentinelConnection, type BymaxCacheStandaloneConnection, CACHE_ERROR_CODES, CACHE_ERROR_MESSAGES, CACHE_EVENT_NAMES, type CacheConnectionStatus, type CacheErrorCode, type CacheEventName, CacheException, type CacheKeyPrefix, type CacheNamespace, CacheService, ConnectionManager, DEFAULT_KEY_SEPARATOR, DEFAULT_NAMESPACE, DEFAULT_REDIS_PORT, type ICacheEvents, type IPubSubHandler, type IPubSubPatternHandler, type IScriptDefinition, type ISerializer, JsonSerializer, KeyBuilder, PubSubService, type ResolvedOptions, ScriptManagerService, type SerializableValue, type Unsubscribe };
+export { BYMAX_CACHE_CONNECTION, BYMAX_CACHE_EVENTS, BYMAX_CACHE_KEY_BUILDER, BYMAX_CACHE_OPTIONS, BYMAX_CACHE_SCRIPT_REGISTRY, BYMAX_CACHE_SERIALIZER, type BymaxCacheClusterConnection, BymaxCacheModule, type BymaxCacheModuleAsyncOptions, type BymaxCacheModuleOptions, type BymaxCacheSentinelConnection, type BymaxCacheStandaloneConnection, CACHE_ERROR_CODES, CACHE_ERROR_MESSAGES, CACHE_EVENT_NAMES, type CacheConnectionStatus, type CacheErrorCode, type CacheEventName, CacheException, type CacheKeyPrefix, type CacheNamespace, CacheService, ConnectionManager, DEFAULT_KEY_SEPARATOR, DEFAULT_NAMESPACE, DEFAULT_REDIS_PORT, type ICacheEvents, type IPubSubHandler, type IPubSubPatternHandler, type IScriptDefinition, type ISerializer, JsonSerializer, KeyBuilder, PubSubService, type ResolvedOptions, ScriptManagerService, type SerializableValue, type Unsubscribe, createConnectionManager };

package/dist/server/index.d.ts

@@ -399,7 +399,8 @@ declare class ConnectionManager implements OnModuleInit, OnModuleDestroy {
      * ready buffers until connected instead of failing fast like the data-plane
      * main client (whose offline queue stays disabled to avoid silent buffering).
      * This override applies to standalone/sentinel modes only; in cluster mode
-     * {@link createClient} ignores it (cluster Pub/Sub is an experimental passthrough).
+     * {@link createClient} ignores it and the cluster client manages its own subscriber
+     * connection.
      *
      * @returns A fresh client wired with `subscriber`-role event listeners.
      */
@@ -432,6 +433,48 @@ declare class ConnectionManager implements OnModuleInit, OnModuleDestroy {
     private waitUntilReady;
 }
 
+/**
+ * Factory for a dedicated, lifecycle-managed Redis connection.
+ *
+ * Layer: server. A consumer that needs a second connection with its own options (for
+ * example a standalone one beside a clustered cache) builds it here instead of
+ * hand-writing the resolved options, which would skip validation and the defaults.
+ */
+
+/**
+ * Builds a {@link ConnectionManager} from the same options `BymaxCacheModule.forRoot`
+ * takes: the options are validated and defaulted exactly as the module does, so an invalid
+ * set throws the same `CacheException` before any client exists.
+ *
+ * The manager owns its connection. Register it as a provider and Nest connects it on
+ * `onModuleInit` and quits it on `onModuleDestroy`, with the forced `disconnect()` after
+ * `shutdownTimeoutMs`; the caller writes neither hook. Reach the client with
+ * `manager.getClient()`. This connection is independent of the one `BymaxCacheModule`
+ * registers, and it applies no namespace: keys written through its client are not
+ * prefixed.
+ *
+ * @param options - The connection options, as for `BymaxCacheModule.forRoot`.
+ * @returns A new manager that has not connected yet.
+ * @throws {CacheException} `SENTINEL_MISCONFIGURED`, `CLUSTER_MISCONFIGURED`,
+ *   `CONNECTION_FAILED` or `INVALID_NAMESPACE` when the options are invalid.
+ * @example
+ * ```ts
+ * export const AUTH_REDIS = Symbol('AUTH_REDIS')
+ *
+ * @Module({
+ *   providers: [
+ *     {
+ *       provide: AUTH_REDIS,
+ *       useFactory: () => createConnectionManager({ connection: { url: 'redis://localhost:6379' } })
+ *     }
+ *   ],
+ *   exports: [AUTH_REDIS]
+ * })
+ * export class AuthRedisModule {}
+ * ```
+ */
+declare function createConnectionManager(options: BymaxCacheModuleOptions): ConnectionManager;
+
 /**
  * Composes Redis keys following `{namespace}{separator}{prefix}{separator}{id}`.
  *
@@ -1343,4 +1386,4 @@ declare const CACHE_EVENT_NAMES: {
     readonly END: "end";
 };
 
-export { BYMAX_CACHE_CONNECTION, BYMAX_CACHE_EVENTS, BYMAX_CACHE_KEY_BUILDER, BYMAX_CACHE_OPTIONS, BYMAX_CACHE_SCRIPT_REGISTRY, BYMAX_CACHE_SERIALIZER, type BymaxCacheClusterConnection, BymaxCacheModule, type BymaxCacheModuleAsyncOptions, type BymaxCacheModuleOptions, type BymaxCacheSentinelConnection, type BymaxCacheStandaloneConnection, CACHE_ERROR_CODES, CACHE_ERROR_MESSAGES, CACHE_EVENT_NAMES, type CacheConnectionStatus, type CacheErrorCode, type CacheEventName, CacheException, type CacheKeyPrefix, type CacheNamespace, CacheService, ConnectionManager, DEFAULT_KEY_SEPARATOR, DEFAULT_NAMESPACE, DEFAULT_REDIS_PORT, type ICacheEvents, type IPubSubHandler, type IPubSubPatternHandler, type IScriptDefinition, type ISerializer, JsonSerializer, KeyBuilder, PubSubService, type ResolvedOptions, ScriptManagerService, type SerializableValue, type Unsubscribe };
+export { BYMAX_CACHE_CONNECTION, BYMAX_CACHE_EVENTS, BYMAX_CACHE_KEY_BUILDER, BYMAX_CACHE_OPTIONS, BYMAX_CACHE_SCRIPT_REGISTRY, BYMAX_CACHE_SERIALIZER, type BymaxCacheClusterConnection, BymaxCacheModule, type BymaxCacheModuleAsyncOptions, type BymaxCacheModuleOptions, type BymaxCacheSentinelConnection, type BymaxCacheStandaloneConnection, CACHE_ERROR_CODES, CACHE_ERROR_MESSAGES, CACHE_EVENT_NAMES, type CacheConnectionStatus, type CacheErrorCode, type CacheEventName, CacheException, type CacheKeyPrefix, type CacheNamespace, CacheService, ConnectionManager, DEFAULT_KEY_SEPARATOR, DEFAULT_NAMESPACE, DEFAULT_REDIS_PORT, type ICacheEvents, type IPubSubHandler, type IPubSubPatternHandler, type IScriptDefinition, type ISerializer, JsonSerializer, KeyBuilder, PubSubService, type ResolvedOptions, ScriptManagerService, type SerializableValue, type Unsubscribe, createConnectionManager };

package/dist/server/index.mjs

@@ -288,6 +288,10 @@ function applyDefaults(options) {
   }
   return Object.freeze(resolved);
 }
+function resolveOptions(options) {
+  validateOptions(options);
+  return applyDefaults(options);
+}
 var _client, _redisOptionsResolved;
 var ConnectionManager = class {
   /**
@@ -352,7 +356,8 @@ var ConnectionManager = class {
    * ready buffers until connected instead of failing fast like the data-plane
    * main client (whose offline queue stays disabled to avoid silent buffering).
    * This override applies to standalone/sentinel modes only; in cluster mode
-   * {@link createClient} ignores it (cluster Pub/Sub is an experimental passthrough).
+   * {@link createClient} ignores it and the cluster client manages its own subscriber
+   * connection.
    *
    * @returns A fresh client wired with `subscriber`-role event listeners.
    */
@@ -1644,8 +1649,7 @@ var BymaxCacheModule = class extends ConfigurableModuleClass {
    *   fail bootstrap validation (e.g. missing connection, misconfigured mode).
    */
   static forRoot(options) {
-    validateOptions(options);
-    const resolved = applyDefaults(options);
+    const resolved = resolveOptions(options);
     const providers = [
       { provide: MODULE_OPTIONS_TOKEN, useValue: options },
       { provide: BYMAX_CACHE_OPTIONS, useValue: resolved },
@@ -1702,10 +1706,7 @@ var BymaxCacheModule = class extends ConfigurableModuleClass {
     return [
       {
         provide: BYMAX_CACHE_OPTIONS,
-        useFactory: (raw) => {
-          validateOptions(raw);
-          return applyDefaults(raw);
-        },
+        useFactory: (raw) => resolveOptions(raw),
         inject: [MODULE_OPTIONS_TOKEN]
       },
       {
@@ -1770,6 +1771,12 @@ BymaxCacheModule = __decorateClass([
   Module({})
 ], BymaxCacheModule);
 
+// src/server/connection/create-connection-manager.ts
+function createConnectionManager(options) {
+  const resolved = resolveOptions(options);
+  return new ConnectionManager(resolved, resolved.events);
+}
+
 // src/shared/constants/event-names.ts
 var CACHE_EVENT_NAMES = {
   CONNECT: "connect",
@@ -1780,4 +1787,4 @@ var CACHE_EVENT_NAMES = {
   END: "end"
 };
 
-export { BYMAX_CACHE_CONNECTION, BYMAX_CACHE_EVENTS, BYMAX_CACHE_KEY_BUILDER, BYMAX_CACHE_OPTIONS, BYMAX_CACHE_SCRIPT_REGISTRY, BYMAX_CACHE_SERIALIZER, BymaxCacheModule, CACHE_ERROR_CODES, CACHE_ERROR_MESSAGES, CACHE_EVENT_NAMES, CacheException, CacheService, ConnectionManager, DEFAULT_KEY_SEPARATOR, DEFAULT_NAMESPACE, DEFAULT_REDIS_PORT, JsonSerializer, KeyBuilder, PubSubService, ScriptManagerService };
+export { BYMAX_CACHE_CONNECTION, BYMAX_CACHE_EVENTS, BYMAX_CACHE_KEY_BUILDER, BYMAX_CACHE_OPTIONS, BYMAX_CACHE_SCRIPT_REGISTRY, BYMAX_CACHE_SERIALIZER, BymaxCacheModule, CACHE_ERROR_CODES, CACHE_ERROR_MESSAGES, CACHE_EVENT_NAMES, CacheException, CacheService, ConnectionManager, DEFAULT_KEY_SEPARATOR, DEFAULT_NAMESPACE, DEFAULT_REDIS_PORT, JsonSerializer, KeyBuilder, PubSubService, ScriptManagerService, createConnectionManager };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-cache",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "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",