@bymax-one/nest-cache 1.0.0

package/dist/server/index.mjs

@@ -0,0 +1,1642 @@
+import { ConfigurableModuleBuilder, HttpStatus, Injectable, Inject, Optional, Module, HttpException } from '@nestjs/common';
+import { Redis, Cluster } from 'ioredis';
+
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (decorator(result)) || result;
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/server/bymax-cache.constants.ts
+var BYMAX_CACHE_OPTIONS = /* @__PURE__ */ Symbol("BYMAX_CACHE_OPTIONS");
+var BYMAX_CACHE_CONNECTION = /* @__PURE__ */ Symbol("BYMAX_CACHE_CONNECTION");
+var BYMAX_CACHE_SCRIPT_REGISTRY = /* @__PURE__ */ Symbol("BYMAX_CACHE_SCRIPT_REGISTRY");
+var BYMAX_CACHE_EVENTS = /* @__PURE__ */ Symbol("BYMAX_CACHE_EVENTS");
+var BYMAX_CACHE_SERIALIZER = /* @__PURE__ */ Symbol("BYMAX_CACHE_SERIALIZER");
+var BYMAX_CACHE_KEY_BUILDER = /* @__PURE__ */ Symbol("BYMAX_CACHE_KEY_BUILDER");
+var { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } = new ConfigurableModuleBuilder({ moduleName: "BymaxCache" }).setClassMethodName("forRoot").setExtras({ isGlobal: true }, (definition, extras) => ({
+  ...definition,
+  global: extras.isGlobal
+})).build();
+
+// src/server/constants/default-namespace.ts
+var DEFAULT_NAMESPACE = "app";
+var DEFAULT_KEY_SEPARATOR = ":";
+
+// src/server/constants/default-timeouts.ts
+var DEFAULT_CONNECT_TIMEOUT_MS = 1e4;
+var DEFAULT_COMMAND_TIMEOUT_MS = 5e3;
+var DEFAULT_SHUTDOWN_TIMEOUT_MS = 5e3;
+var DEFAULT_MAX_RETRIES_PER_REQUEST = 3;
+var DEFAULT_RETRY_BASE_MS = 50;
+var DEFAULT_RETRY_MAX_MS = 2e3;
+var MIN_SHUTDOWN_TIMEOUT_MS = 100;
+var MIN_CONNECT_TIMEOUT_MS = 100;
+
+// src/shared/constants/error-codes.ts
+var CACHE_ERROR_CODES = {
+  CONNECTION_FAILED: "cache.connection_failed",
+  COMMAND_TIMEOUT: "cache.command_timeout",
+  CONNECTION_LOST: "cache.connection_lost",
+  SERIALIZATION_FAILED: "cache.serialization_failed",
+  DESERIALIZATION_FAILED: "cache.deserialization_failed",
+  INVALID_NAMESPACE: "cache.invalid_namespace",
+  INVALID_KEY: "cache.invalid_key",
+  SCRIPT_NOT_REGISTERED: "cache.script_not_registered",
+  SCRIPT_EXECUTION_FAILED: "cache.script_execution_failed",
+  SCRIPT_REGISTRY_MISSING: "cache.script_registry_missing",
+  FLUSH_DISABLED_IN_PRODUCTION: "cache.flush_disabled_in_production",
+  CLUSTER_MISCONFIGURED: "cache.cluster_misconfigured",
+  SENTINEL_MISCONFIGURED: "cache.sentinel_misconfigured",
+  SHUTDOWN_TIMEOUT: "cache.shutdown_timeout",
+  UNSUPPORTED_IN_CLUSTER: "cache.unsupported_in_cluster"
+};
+
+// src/server/errors/cache-error-codes.ts
+var CACHE_ERROR_MESSAGES = /* @__PURE__ */ new Map([
+  [CACHE_ERROR_CODES.CONNECTION_FAILED, "Could not connect to Redis after retries."],
+  [CACHE_ERROR_CODES.COMMAND_TIMEOUT, "Redis command timed out."],
+  [CACHE_ERROR_CODES.CONNECTION_LOST, "Redis connection was lost during the operation."],
+  [CACHE_ERROR_CODES.SERIALIZATION_FAILED, "Failed to serialize the value."],
+  [CACHE_ERROR_CODES.DESERIALIZATION_FAILED, "Failed to deserialize the cached value."],
+  [CACHE_ERROR_CODES.INVALID_NAMESPACE, "Namespace is empty or contains the reserved separator."],
+  [CACHE_ERROR_CODES.INVALID_KEY, "Cache key prefix or id is empty."],
+  [CACHE_ERROR_CODES.SCRIPT_NOT_REGISTERED, "Tried to execute an unregistered Lua script."],
+  [CACHE_ERROR_CODES.SCRIPT_EXECUTION_FAILED, "Lua script returned a Redis error."],
+  [CACHE_ERROR_CODES.SCRIPT_REGISTRY_MISSING, "eval called without registering any scripts."],
+  [CACHE_ERROR_CODES.FLUSH_DISABLED_IN_PRODUCTION, "flushNamespace is disabled in production."],
+  [CACHE_ERROR_CODES.CLUSTER_MISCONFIGURED, "Cluster mode requires cluster.nodes."],
+  [
+    CACHE_ERROR_CODES.SENTINEL_MISCONFIGURED,
+    "Sentinel mode requires sentinel.sentinels and sentinel.name."
+  ],
+  [CACHE_ERROR_CODES.SHUTDOWN_TIMEOUT, "Graceful shutdown exceeded the timeout."],
+  [
+    CACHE_ERROR_CODES.UNSUPPORTED_IN_CLUSTER,
+    "This operation requires standalone or sentinel mode; it is not supported in cluster mode."
+  ]
+]);
+var CACHE_ERROR_STATUS = /* @__PURE__ */ new Map([
+  [CACHE_ERROR_CODES.COMMAND_TIMEOUT, HttpStatus.GATEWAY_TIMEOUT],
+  [CACHE_ERROR_CODES.CONNECTION_LOST, HttpStatus.SERVICE_UNAVAILABLE],
+  [CACHE_ERROR_CODES.INVALID_KEY, HttpStatus.BAD_REQUEST],
+  [CACHE_ERROR_CODES.FLUSH_DISABLED_IN_PRODUCTION, HttpStatus.FORBIDDEN]
+]);
+var CacheException = class extends HttpException {
+  /**
+   * @param code - One of {@link CACHE_ERROR_CODES}.
+   * @param details - Optional structured context. Never include secret values.
+   * @param statusCode - HTTP status override. When omitted, defaults to the
+   *   canonical status for `code` (§12.2), or 500 for codes whose canonical
+   *   status is 500.
+   */
+  constructor(code, details, statusCode) {
+    super(
+      {
+        error: {
+          code,
+          message: CACHE_ERROR_MESSAGES.get(code) ?? "Cache error",
+          details: details ?? null
+        }
+      },
+      statusCode ?? CACHE_ERROR_STATUS.get(code) ?? HttpStatus.INTERNAL_SERVER_ERROR
+    );
+    this.code = code;
+    this.details = details ?? null;
+  }
+};
+
+// src/server/utils/parse-redis-url.ts
+function parseRedisUrl(url) {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "redis:" && parsed.protocol !== "rediss:") {
+    throw new Error(`Unsupported Redis protocol: ${parsed.protocol}`);
+  }
+  if (parsed.hostname === "") {
+    throw new Error("Redis URL is missing a host");
+  }
+  const result = {
+    host: parsed.hostname,
+    port: parsed.port ? Number.parseInt(parsed.port, 10) : 6379
+  };
+  if (parsed.username) {
+    result.username = decodeURIComponent(parsed.username);
+  }
+  if (parsed.password) {
+    result.password = decodeURIComponent(parsed.password);
+  }
+  const dbSegment = parsed.pathname.slice(1);
+  if (dbSegment && /^\d+$/.test(dbSegment)) {
+    result.db = Number.parseInt(dbSegment, 10);
+  }
+  if (parsed.protocol === "rediss:") {
+    result.tls = {};
+  }
+  return result;
+}
+
+// src/server/config/default-options.ts
+function validateOptions(options) {
+  const mode = options.mode ?? "standalone";
+  if (mode === "sentinel") {
+    if (!options.sentinel || !options.sentinel.sentinels?.length || !options.sentinel.name) {
+      throw new CacheException(CACHE_ERROR_CODES.SENTINEL_MISCONFIGURED, { mode });
+    }
+  }
+  if (mode === "cluster") {
+    if (!options.cluster || !options.cluster.nodes?.length) {
+      throw new CacheException(CACHE_ERROR_CODES.CLUSTER_MISCONFIGURED, { mode });
+    }
+  }
+  if (mode === "standalone") {
+    const connection = options.connection;
+    if (!connection || !connection.url && !connection.host) {
+      throw new CacheException(CACHE_ERROR_CODES.CONNECTION_FAILED, {
+        reason: "missing connection.url or connection.host"
+      });
+    }
+    if (connection.url) {
+      try {
+        parseRedisUrl(connection.url);
+      } catch {
+        throw new CacheException(CACHE_ERROR_CODES.CONNECTION_FAILED, {
+          reason: "invalid connection.url"
+        });
+      }
+    }
+  }
+  const namespace = options.namespace ?? DEFAULT_NAMESPACE;
+  const separator = options.keySeparator ?? DEFAULT_KEY_SEPARATOR;
+  if (!namespace || namespace.trim() === "") {
+    throw new CacheException(CACHE_ERROR_CODES.INVALID_NAMESPACE, { namespace });
+  }
+  if (namespace.includes(separator)) {
+    throw new CacheException(CACHE_ERROR_CODES.INVALID_NAMESPACE, {
+      reason: "namespace contains key separator",
+      namespace,
+      separator
+    });
+  }
+  const shutdown = options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
+  if (shutdown < MIN_SHUTDOWN_TIMEOUT_MS) {
+    throw new CacheException(CACHE_ERROR_CODES.CONNECTION_FAILED, {
+      reason: "shutdownTimeoutMs too low",
+      value: shutdown,
+      min: MIN_SHUTDOWN_TIMEOUT_MS
+    });
+  }
+  const connectTimeout = options.connection?.connectTimeout;
+  if (connectTimeout !== void 0 && connectTimeout < MIN_CONNECT_TIMEOUT_MS) {
+    throw new CacheException(CACHE_ERROR_CODES.CONNECTION_FAILED, {
+      reason: "connectTimeout too low",
+      value: connectTimeout,
+      min: MIN_CONNECT_TIMEOUT_MS
+    });
+  }
+}
+function applyDefaults(options) {
+  const resolved = {
+    mode: options.mode ?? "standalone",
+    connection: options.connection,
+    sentinel: options.sentinel,
+    cluster: options.cluster,
+    namespace: options.namespace ?? DEFAULT_NAMESPACE,
+    keySeparator: options.keySeparator ?? DEFAULT_KEY_SEPARATOR,
+    serializer: options.serializer,
+    events: options.events,
+    shutdownTimeoutMs: options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS,
+    allowFlushInProduction: options.allowFlushInProduction ?? false,
+    isGlobal: options.isGlobal ?? true,
+    scripts: options.scripts
+  };
+  return Object.freeze(resolved);
+}
+var ConnectionManager = class {
+  /**
+   * @param options - Resolved module options (frozen).
+   * @param events - Optional consumer event callbacks; `@Optional()` so the
+   *   module can provide `null` when the consumer omits `events`.
+   */
+  constructor(options, events) {
+    this.options = options;
+    this.events = events;
+    this.client = null;
+    /** Default backoff: grow 50 ms per attempt, capped at 2 s. */
+    this.defaultRetryStrategy = (times) => Math.min(times * DEFAULT_RETRY_BASE_MS, DEFAULT_RETRY_MAX_MS);
+    /** Default reconnect policy: reconnect only on a `READONLY` replica failover. */
+    this.defaultReconnectOnError = (err) => err.message.includes("READONLY");
+    this.redisOptionsResolved = this.buildRedisOptions(options);
+  }
+  /** Opens the main client and waits for readiness unless `lazyConnect`. */
+  async onModuleInit() {
+    this.client = this.createClient();
+    this.registerListeners(this.client, "main");
+    if (!this.options.connection?.lazyConnect) {
+      await this.waitUntilReady(this.client);
+    }
+  }
+  /**
+   * Returns the singleton main client, creating it on first access if the
+   * module init has not run yet.
+   *
+   * @returns The shared main client.
+   */
+  getClient() {
+    if (!this.client) {
+      this.client = this.createClient();
+      this.registerListeners(this.client, "main");
+    }
+    return this.client;
+  }
+  /**
+   * Creates a brand-new dedicated connection for subscriber mode (a subscriber
+   * connection cannot run normal commands), inheriting the main options.
+   *
+   * Ownership of the returned client transfers to the caller: `onModuleDestroy`
+   * quits only the main client, so a subscriber client must be quit/disconnected
+   * by its owner (the Pub/Sub service).
+   *
+   * The subscriber is a control-plane connection (only SUBSCRIBE / UNSUBSCRIBE),
+   * so its offline queue is enabled — a subscribe issued before the socket is
+   * 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).
+   *
+   * @returns A fresh client wired with `subscriber`-role event listeners.
+   */
+  createSubscriberClient() {
+    const client = this.createClient({ enableOfflineQueue: true });
+    this.registerListeners(client, "subscriber");
+    return client;
+  }
+  /** Quits the main client gracefully, forcing `disconnect()` on timeout. */
+  async onModuleDestroy() {
+    const client = this.client;
+    if (!client) {
+      return;
+    }
+    let timer;
+    try {
+      await Promise.race([
+        client.quit(),
+        new Promise((_resolve, reject) => {
+          timer = setTimeout(
+            () => reject(
+              new CacheException(CACHE_ERROR_CODES.SHUTDOWN_TIMEOUT, {
+                timeoutMs: this.options.shutdownTimeoutMs
+              })
+            ),
+            this.options.shutdownTimeoutMs
+          );
+        })
+      ]);
+    } catch {
+      this.emit("error", {
+        role: "main",
+        reason: "forced_disconnect",
+        shutdownTimeoutMs: this.options.shutdownTimeoutMs
+      });
+      client.disconnect();
+    } finally {
+      clearTimeout(timer);
+      this.client = null;
+    }
+  }
+  // ─── Private ──────────────────────────────────────────────────────────────
+  /**
+   * Instantiates the client matching the configured mode.
+   *
+   * @param overrides - Extra `RedisOptions` merged over the resolved defaults
+   *   (used to enable the subscriber's offline queue). Ignored in cluster mode,
+   *   where Pub/Sub has different semantics and is out of scope.
+   */
+  createClient(overrides) {
+    if (this.options.mode === "sentinel") {
+      const sentinel = this.options.sentinel;
+      if (!sentinel) {
+        throw new CacheException(CACHE_ERROR_CODES.SENTINEL_MISCONFIGURED, { mode: "sentinel" });
+      }
+      return new Redis({
+        ...this.redisOptionsResolved,
+        ...overrides,
+        sentinels: sentinel.sentinels,
+        name: sentinel.name,
+        ...sentinel.sentinelPassword !== void 0 && {
+          sentinelPassword: sentinel.sentinelPassword
+        },
+        ...sentinel.password !== void 0 && { password: sentinel.password },
+        // Normalize 'replica' → 'slave' — ioredis 5 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
+        },
+        ...sentinel.natMap !== void 0 && { natMap: sentinel.natMap }
+      });
+    }
+    if (this.options.mode === "cluster") {
+      const cluster = this.options.cluster;
+      if (!cluster) {
+        throw new CacheException(CACHE_ERROR_CODES.CLUSTER_MISCONFIGURED, { mode: "cluster" });
+      }
+      return new Cluster(cluster.nodes, cluster.options ?? {});
+    }
+    return new Redis({ ...this.redisOptionsResolved, ...overrides });
+  }
+  /** Merges connection options with defaults; URL fields take precedence. */
+  buildRedisOptions(opts) {
+    const c = opts.connection ?? {};
+    const fromUrl = c.url ? parseRedisUrl(c.url) : {};
+    return {
+      lazyConnect: c.lazyConnect ?? false,
+      connectTimeout: c.connectTimeout ?? DEFAULT_CONNECT_TIMEOUT_MS,
+      commandTimeout: c.commandTimeout ?? DEFAULT_COMMAND_TIMEOUT_MS,
+      maxRetriesPerRequest: c.maxRetriesPerRequest ?? DEFAULT_MAX_RETRIES_PER_REQUEST,
+      enableReadyCheck: c.enableReadyCheck ?? true,
+      enableOfflineQueue: c.enableOfflineQueue ?? false,
+      retryStrategy: c.retryStrategy ?? this.defaultRetryStrategy,
+      reconnectOnError: c.reconnectOnError ?? this.defaultReconnectOnError,
+      keepAlive: c.keepAlive ?? 0,
+      noDelay: c.noDelay ?? true,
+      family: c.family ?? 4,
+      ...c.host !== void 0 && { host: c.host },
+      ...c.port !== void 0 && { port: c.port },
+      ...c.password !== void 0 && { password: c.password },
+      ...c.db !== void 0 && { db: c.db },
+      ...c.username !== void 0 && { username: c.username },
+      ...c.tls !== void 0 && { tls: c.tls },
+      ...fromUrl
+    };
+  }
+  /** Forwards a lifecycle event to `events.onEvent`, swallowing consumer throws. */
+  emit(event, data) {
+    try {
+      this.events?.onEvent?.(event, data);
+    } catch {
+    }
+  }
+  /** Wires lifecycle listeners that forward to `events.onEvent`, swallowing throws. */
+  registerListeners(client, role) {
+    client.on("connect", () => this.emit("connect", { role }));
+    client.on("ready", () => this.emit("ready", { role }));
+    client.on("error", (err) => this.emit("error", { role, error: err.message }));
+    client.on("close", () => this.emit("close", { role }));
+    client.on("reconnecting", (delay) => this.emit("reconnecting", { role, delay }));
+    client.on("end", () => this.emit("end", { role }));
+  }
+  /** Resolves once the client is ready; rejects (wrapped) on connection error. */
+  async waitUntilReady(client) {
+    if (client.status === "ready") {
+      return;
+    }
+    await new Promise((resolve, reject) => {
+      const cleanup = () => {
+        client.off("ready", onReady);
+        client.off("error", onError);
+      };
+      const onReady = () => {
+        cleanup();
+        resolve();
+      };
+      const onError = (err) => {
+        cleanup();
+        reject(new CacheException(CACHE_ERROR_CODES.CONNECTION_FAILED, { error: err.message }));
+      };
+      client.once("ready", onReady);
+      client.once("error", onError);
+    });
+  }
+};
+ConnectionManager = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(BYMAX_CACHE_OPTIONS)),
+  __decorateParam(1, Optional()),
+  __decorateParam(1, Inject(BYMAX_CACHE_EVENTS))
+], ConnectionManager);
+var SCRIPT_LOAD = "LOAD";
+var NOSCRIPT_MARKER = "NOSCRIPT";
+var toErrorMessage = (err) => err instanceof Error ? err.message : String(err);
+var ScriptManagerService = class {
+  /**
+   * @param options - Resolved module options; `options.scripts` seeds the registry.
+   * @param connection - Owns the client used for `SCRIPT LOAD` / `EVALSHA`.
+   *   Explicit `@Inject` — the published bundle is built without
+   *   emitDecoratorMetadata, so type-only DI cannot resolve a class provider
+   *   (CLAUDE.md §5).
+   */
+  constructor(options, connection) {
+    this.options = options;
+    this.connection = connection;
+    /** Registry of script name → `{ lua, sha? }`. */
+    this.scripts = /* @__PURE__ */ new Map();
+    for (const definition of options.scripts ?? []) {
+      this.scripts.set(definition.name, { lua: definition.lua });
+    }
+  }
+  /**
+   * Pre-loads every registered script once the application has bootstrapped,
+   * unless `lazyConnect` is set — in which case loading is deferred to the first
+   * {@link eval}.
+   *
+   * Runs in `onApplicationBootstrap` (not `onModuleInit`) deliberately: NestJS
+   * invokes `onModuleInit` hooks concurrently, so loading here would race the
+   * {@link ConnectionManager} connect and fail fast against a not-yet-writable
+   * socket (offline queue is disabled). `onApplicationBootstrap` is guaranteed to
+   * run after every `onModuleInit` resolved — i.e. once the connection is ready.
+   *
+   * @returns Resolves once all eager scripts are loaded.
+   */
+  async onApplicationBootstrap() {
+    if (this.options.connection?.lazyConnect) {
+      return;
+    }
+    await Promise.all([...this.scripts.keys()].map((name) => this.load(name)));
+  }
+  /**
+   * Registers a script under `name`, or overrides an existing one. The new
+   * script is loaded lazily on its next {@link eval} / {@link load}.
+   *
+   * @param name - Lookup name used to invoke the script.
+   * @param lua - The Lua source. Never build this from untrusted input (CLAUDE.md §4).
+   */
+  register(name, lua) {
+    this.scripts.set(name, { lua });
+  }
+  /**
+   * Loads a registered script into Redis (if not already cached) and returns its
+   * SHA1. Idempotent — a cached SHA is reused without a second `SCRIPT LOAD`.
+   *
+   * @param name - The registered script name.
+   * @returns The script's SHA1.
+   * @throws {CacheException} `SCRIPT_NOT_REGISTERED` when `name` is unknown.
+   */
+  async load(name) {
+    const entry = this.scripts.get(name);
+    if (!entry) {
+      throw new CacheException(CACHE_ERROR_CODES.SCRIPT_NOT_REGISTERED, { name });
+    }
+    if (!entry.sha) {
+      const client = this.connection.getClient();
+      entry.sha = await client.script(SCRIPT_LOAD, entry.lua);
+    }
+    return entry.sha;
+  }
+  /**
+   * Executes a registered Lua script.
+   *
+   * Standalone / sentinel use `EVALSHA`; on `NOSCRIPT` the script is reloaded once
+   * and the call retried. CLUSTER uses `EVAL` (the full body): `EVALSHA` routes to
+   * the key's slot owner while `SCRIPT LOAD` is keyless (lands on an arbitrary
+   * node), so the owner could `NOSCRIPT` and a keyless reload would not fix it —
+   * `EVAL` ships the body and routes by key to the slot owner; a keyless `EVAL`
+   * would execute on an arbitrary node — this method throws
+   * `SCRIPT_EXECUTION_FAILED` when called in cluster mode with zero keys.
+   *
+   * Keys must already be namespaced — {@link CacheService.eval} handles that for
+   * consumer-facing usage. In cluster mode all keys of a single call must hash to
+   * the same slot (use a hash tag), per Redis cluster semantics.
+   *
+   * @param name - The registered script name.
+   * @param keys - `KEYS[]` for the script (already namespaced).
+   * @param args - `ARGV[]` for the script.
+   * @returns The script's return value, typed `unknown` (Redis Lua is dynamic).
+   * @throws {CacheException} `SCRIPT_NOT_REGISTERED` when `name` is unknown.
+   * @throws {CacheException} `SCRIPT_EXECUTION_FAILED` on a non-`NOSCRIPT` error,
+   *   a failed reload-and-retry, or any cluster `EVAL` failure. The Lua source is
+   *   never echoed in the error.
+   */
+  async eval(name, keys, args) {
+    const entry = this.scripts.get(name);
+    if (!entry) {
+      throw new CacheException(CACHE_ERROR_CODES.SCRIPT_NOT_REGISTERED, { name });
+    }
+    const client = this.connection.getClient();
+    if (this.options.mode === "cluster") {
+      if (keys.length === 0) {
+        throw new CacheException(CACHE_ERROR_CODES.SCRIPT_EXECUTION_FAILED, {
+          name,
+          reason: "cluster EVAL requires at least one key for slot routing"
+        });
+      }
+      try {
+        return await client.eval(entry.lua, keys.length, ...keys, ...args);
+      } catch (err) {
+        throw new CacheException(CACHE_ERROR_CODES.SCRIPT_EXECUTION_FAILED, {
+          name,
+          originalError: toErrorMessage(err)
+        });
+      }
+    }
+    try {
+      const sha = entry.sha ?? await this.load(name);
+      return await client.evalsha(sha, keys.length, ...keys, ...args);
+    } catch (err) {
+      if (!toErrorMessage(err).includes(NOSCRIPT_MARKER)) {
+        throw new CacheException(CACHE_ERROR_CODES.SCRIPT_EXECUTION_FAILED, {
+          name,
+          originalError: toErrorMessage(err)
+        });
+      }
+      try {
+        const reloadedSha = await client.script(SCRIPT_LOAD, entry.lua);
+        entry.sha = reloadedSha;
+        return await client.evalsha(reloadedSha, keys.length, ...keys, ...args);
+      } catch (retryErr) {
+        throw new CacheException(CACHE_ERROR_CODES.SCRIPT_EXECUTION_FAILED, {
+          name,
+          originalError: toErrorMessage(retryErr)
+        });
+      }
+    }
+  }
+};
+ScriptManagerService = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(BYMAX_CACHE_OPTIONS)),
+  __decorateParam(1, Inject(ConnectionManager))
+], ScriptManagerService);
+var KeyBuilder = class {
+  /**
+   * @param options - Resolved module options supplying the namespace + separator.
+   */
+  constructor(options) {
+    this.namespace = options.namespace;
+    this.separator = options.keySeparator;
+  }
+  /**
+   * Builds the full namespaced key.
+   *
+   * @param prefix - The entity-group prefix (e.g. `'users'`).
+   * @param id - The entity id.
+   * @returns `{namespace}{sep}{prefix}{sep}{id}`.
+   * @throws {CacheException} `INVALID_KEY` when `prefix` or `id` is empty.
+   */
+  build(prefix, id) {
+    if (!prefix) {
+      throw new CacheException(CACHE_ERROR_CODES.INVALID_KEY, { reason: "empty_prefix" });
+    }
+    if (!id) {
+      throw new CacheException(CACHE_ERROR_CODES.INVALID_KEY, { reason: "empty_id" });
+    }
+    return `${this.namespace}${this.separator}${prefix}${this.separator}${id}`;
+  }
+  /**
+   * Applies only the namespace to an already-composed key. Used by the Pub/Sub
+   * and script services for channel/key namespacing.
+   *
+   * @param keyWithoutNamespace - The bare key to namespace.
+   * @returns `{namespace}{sep}{keyWithoutNamespace}`.
+   * @throws {CacheException} `INVALID_KEY` when the key is empty.
+   */
+  applyNamespace(keyWithoutNamespace) {
+    if (!keyWithoutNamespace) {
+      throw new CacheException(CACHE_ERROR_CODES.INVALID_KEY, { reason: "empty_key" });
+    }
+    return `${this.namespace}${this.separator}${keyWithoutNamespace}`;
+  }
+  /**
+   * Returns the `{namespace}{separator}` prefix string used to build `SCAN`
+   * match patterns scoped to this namespace.
+   *
+   * @returns The namespace prefix, e.g. `'app:'`.
+   */
+  getNamespacePrefix() {
+    return `${this.namespace}${this.separator}`;
+  }
+};
+KeyBuilder = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(BYMAX_CACHE_OPTIONS))
+], KeyBuilder);
+var MAX_PREVIEW_LENGTH = 100;
+var extractErrorMessage = (err) => err instanceof Error ? err.message : String(err);
+var JsonSerializer = class {
+  /**
+   * Encodes a value as a JSON string.
+   *
+   * @typeParam T - The value's static type.
+   * @param value - The value to encode.
+   * @returns The JSON string representation.
+   * @throws {CacheException} `SERIALIZATION_FAILED` when the value cannot be
+   *   stringified. This covers `JSON.stringify` throwing (circular reference,
+   *   `BigInt`) AND the silent cases where a top-level `undefined`, function, or
+   *   `symbol` would make `JSON.stringify` return the JS value `undefined`
+   *   instead of a string. The original message is attached under
+   *   `details.error`; the value itself is never echoed, as it may carry secrets
+   *   (CLAUDE.md §4).
+   */
+  serialize(value) {
+    if (value === void 0 || typeof value === "function" || typeof value === "symbol") {
+      throw new CacheException(CACHE_ERROR_CODES.SERIALIZATION_FAILED, {
+        error: "Cannot serialize a top-level undefined, function, or symbol value"
+      });
+    }
+    try {
+      return JSON.stringify(value);
+    } catch (err) {
+      throw new CacheException(CACHE_ERROR_CODES.SERIALIZATION_FAILED, {
+        error: extractErrorMessage(err)
+      });
+    }
+  }
+  /**
+   * Decodes a JSON string back into a value.
+   *
+   * Fails closed: a malformed payload throws instead of returning `undefined`
+   * or a partial value, so a corrupted cache entry can never masquerade as a
+   * valid `T` (security invariant — CLAUDE.md §4).
+   *
+   * @typeParam T - The expected decoded type.
+   * @param raw - The JSON string to decode.
+   * @returns The decoded value, typed as `T`.
+   * @throws {CacheException} `DESERIALIZATION_FAILED` when `raw` is not valid
+   *   JSON. `details.preview` carries at most {@link MAX_PREVIEW_LENGTH}
+   *   characters of `raw` (truncated with an ellipsis) to aid debugging without
+   *   leaking a large payload that may contain PII.
+   */
+  deserialize(raw) {
+    try {
+      return JSON.parse(raw);
+    } catch (err) {
+      throw new CacheException(CACHE_ERROR_CODES.DESERIALIZATION_FAILED, {
+        error: extractErrorMessage(err),
+        preview: raw.length > MAX_PREVIEW_LENGTH ? `${raw.substring(0, MAX_PREVIEW_LENGTH)}...` : raw
+      });
+    }
+  }
+};
+JsonSerializer = __decorateClass([
+  Injectable()
+], JsonSerializer);
+
+// src/server/utils/resolve-serializer.ts
+var resolveSerializer = (options, injected) => (
+  // JsonSerializer has no constructor arguments; manual instantiation is intentional
+  // here so this utility has no NestJS DI dependency and stays importable anywhere.
+  options.serializer ?? injected ?? new JsonSerializer()
+);
+
+// src/server/services/cache.service.ts
+var PRODUCTION_ENV = "production";
+var SCAN_COUNT = 100;
+var FLUSH_SCAN_COUNT = 1e3;
+var isScannableClient = (client) => typeof client.scanStream === "function";
+var CacheService = class {
+  /**
+   * @param options - Resolved module options (frozen). Supplies `serializer`
+   *   and `allowFlushInProduction`.
+   * @param connection - Owns the singleton ioredis client every command runs on.
+   * @param keyBuilder - Composes every namespaced key.
+   * @param injectedSerializer - Optional `BYMAX_CACHE_SERIALIZER` provider; used
+   *   only when `options.serializer` is absent. `@Optional()` so the token may be
+   *   unprovided in tests / minimal wirings.
+   * @param scriptRegistry - Optional `ScriptManagerService`; required only for
+   *   {@link CacheService.eval}. `@Optional()` so the cache works without scripts.
+   */
+  constructor(options, connection, keyBuilder, injectedSerializer, scriptRegistry) {
+    this.options = options;
+    this.connection = connection;
+    this.keyBuilder = keyBuilder;
+    this.scriptRegistry = scriptRegistry;
+    this.serializer = resolveSerializer(options, injectedSerializer);
+  }
+  // ─── String / value commands ───────────────────────────────────────────────
+  /**
+   * Reads a value and deserializes it through the configured serializer.
+   *
+   * @typeParam T - The expected decoded type.
+   * @param prefix - Entity-group prefix (e.g. `'users'`).
+   * @param id - Entity id.
+   * @returns The decoded value, or `null` when the key does not exist.
+   * @throws {CacheException} `DESERIALIZATION_FAILED` when the stored payload is
+   *   not decodable as `T`.
+   */
+  async get(prefix, id) {
+    const key = this.keyBuilder.build(prefix, id);
+    const raw = await this.connection.getClient().get(key);
+    if (raw === null) {
+      return null;
+    }
+    return this.serializer.deserialize(raw);
+  }
+  /**
+   * Reads the raw stored string without deserialization.
+   *
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id.
+   * @returns The raw string, or `null` when the key does not exist.
+   */
+  async getRaw(prefix, id) {
+    return this.connection.getClient().get(this.keyBuilder.build(prefix, id));
+  }
+  /**
+   * Serializes and writes a value, optionally with a TTL.
+   *
+   * @typeParam T - The value's static type.
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id.
+   * @param value - The value to store (passed through the serializer).
+   * @param ttlSeconds - Optional expiry in seconds; omit for no expiration.
+   * @returns Resolves once the write completes.
+   * @throws {CacheException} `SERIALIZATION_FAILED` when `value` cannot be encoded.
+   */
+  async set(prefix, id, value, ttlSeconds) {
+    const key = this.keyBuilder.build(prefix, id);
+    const raw = this.serializer.serialize(value);
+    if (ttlSeconds !== void 0) {
+      await this.connection.getClient().set(key, raw, "EX", ttlSeconds);
+    } else {
+      await this.connection.getClient().set(key, raw);
+    }
+  }
+  /**
+   * Writes a raw string without serialization, optionally with a TTL.
+   *
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id.
+   * @param value - The raw string to store as-is.
+   * @param ttlSeconds - Optional expiry in seconds; omit for no expiration.
+   * @returns Resolves once the write completes.
+   */
+  async setRaw(prefix, id, value, ttlSeconds) {
+    const key = this.keyBuilder.build(prefix, id);
+    if (ttlSeconds !== void 0) {
+      await this.connection.getClient().set(key, value, "EX", ttlSeconds);
+    } else {
+      await this.connection.getClient().set(key, value);
+    }
+  }
+  /**
+   * Atomically writes a value only if the key does not already exist (`SET NX`).
+   *
+   * @typeParam T - The value's static type.
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id.
+   * @param value - The value to store (passed through the serializer).
+   * @param ttlSeconds - Optional expiry in seconds applied on the same atomic write.
+   * @returns `true` when the value was stored, `false` when the key already existed.
+   * @throws {CacheException} `SERIALIZATION_FAILED` when `value` cannot be encoded.
+   */
+  async setNx(prefix, id, value, ttlSeconds) {
+    const key = this.keyBuilder.build(prefix, id);
+    const raw = this.serializer.serialize(value);
+    const result = ttlSeconds !== void 0 ? await this.connection.getClient().set(key, raw, "EX", ttlSeconds, "NX") : await this.connection.getClient().set(key, raw, "NX");
+    return result === "OK";
+  }
+  /**
+   * Deletes a single key.
+   *
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id.
+   * @returns The number of keys removed (`0` or `1`).
+   */
+  async del(prefix, id) {
+    return this.connection.getClient().del(this.keyBuilder.build(prefix, id));
+  }
+  /**
+   * Deletes many keys under the same prefix in one round trip.
+   *
+   * @param prefix - Entity-group prefix shared by every id.
+   * @param ids - Entity ids to delete. An empty list is a no-op (no Redis call).
+   * @returns The number of keys actually removed.
+   */
+  async delMany(prefix, ids) {
+    if (ids.length === 0) {
+      return 0;
+    }
+    const keys = ids.map((id) => this.keyBuilder.build(prefix, id));
+    return this.connection.getClient().del(...keys);
+  }
+  /**
+   * Reports whether a key exists.
+   *
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id.
+   * @returns `true` when the key exists, otherwise `false`.
+   */
+  async exists(prefix, id) {
+    const count = await this.connection.getClient().exists(this.keyBuilder.build(prefix, id));
+    return count > 0;
+  }
+  // ─── Numeric commands ──────────────────────────────────────────────────────
+  /**
+   * Atomically increments a counter.
+   *
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id.
+   * @param by - Increment step. Defaults to `1` (uses `INCR`); any other value
+   *   uses `INCRBY`.
+   * @returns The value after the increment.
+   */
+  async incr(prefix, id, by = 1) {
+    const key = this.keyBuilder.build(prefix, id);
+    return by === 1 ? this.connection.getClient().incr(key) : this.connection.getClient().incrby(key, by);
+  }
+  /**
+   * Atomically decrements a counter.
+   *
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id.
+   * @param by - Decrement step. Defaults to `1` (uses `DECR`); any other value
+   *   uses `DECRBY`.
+   * @returns The value after the decrement.
+   */
+  async decr(prefix, id, by = 1) {
+    const key = this.keyBuilder.build(prefix, id);
+    return by === 1 ? this.connection.getClient().decr(key) : this.connection.getClient().decrby(key, by);
+  }
+  // ─── Expiration commands ───────────────────────────────────────────────────
+  /**
+   * Sets a TTL on an existing key.
+   *
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id.
+   * @param ttlSeconds - Expiry in seconds.
+   * @returns `true` when the timeout was set, `false` when the key does not exist.
+   */
+  async expire(prefix, id, ttlSeconds) {
+    const result = await this.connection.getClient().expire(this.keyBuilder.build(prefix, id), ttlSeconds);
+    return result === 1;
+  }
+  /**
+   * Reads the remaining TTL of a key.
+   *
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id.
+   * @returns TTL in seconds; `-2` when the key does not exist, `-1` when it
+   *   exists with no expiration.
+   */
+  async ttl(prefix, id) {
+    return this.connection.getClient().ttl(this.keyBuilder.build(prefix, id));
+  }
+  /**
+   * Removes the TTL of a key, making it persistent.
+   *
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id.
+   * @returns `true` when a timeout was removed, `false` when the key has no TTL
+   *   or does not exist.
+   */
+  async persist(prefix, id) {
+    const result = await this.connection.getClient().persist(this.keyBuilder.build(prefix, id));
+    return result === 1;
+  }
+  // ─── Batch commands ────────────────────────────────────────────────────────
+  /**
+   * Reads many keys under the same prefix and deserializes each present value.
+   *
+   * @typeParam T - The expected decoded type of every value.
+   * @param prefix - Entity-group prefix shared by every id.
+   * @param ids - Entity ids to read. An empty list returns `[]` with no Redis call.
+   * @returns Values positionally aligned with `ids`; `null` for missing keys.
+   * @throws {CacheException} `DESERIALIZATION_FAILED` when any present payload is
+   *   not decodable as `T`.
+   */
+  async mget(prefix, ids) {
+    if (ids.length === 0) {
+      return [];
+    }
+    const keys = ids.map((id) => this.keyBuilder.build(prefix, id));
+    const values = await this.connection.getClient().mget(...keys);
+    return values.map((value) => value === null ? null : this.serializer.deserialize(value));
+  }
+  /**
+   * Writes many `[id, value]` pairs under the same prefix in one round trip.
+   *
+   * @typeParam T - The values' static type.
+   * @param prefix - Entity-group prefix shared by every entry.
+   * @param entries - `[id, value]` tuples. An empty list is a no-op (no Redis call).
+   * @returns Resolves once the write completes.
+   * @throws {CacheException} `SERIALIZATION_FAILED` when any value cannot be encoded.
+   */
+  async mset(prefix, entries) {
+    if (entries.length === 0) {
+      return;
+    }
+    const pairs = [];
+    for (const [id, value] of entries) {
+      pairs.push(this.keyBuilder.build(prefix, id), this.serializer.serialize(value));
+    }
+    await this.connection.getClient().mset(...pairs);
+  }
+  // ─── Hash commands ─────────────────────────────────────────────────────────
+  /**
+   * Reads one hash field and deserializes its value.
+   *
+   * @typeParam T - The expected decoded type.
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id (the hash key).
+   * @param field - Hash field name (kept raw, never serialized).
+   * @returns The decoded field value, or `null` when the field does not exist.
+   * @throws {CacheException} `DESERIALIZATION_FAILED` when the field payload is
+   *   not decodable as `T`.
+   */
+  async hget(prefix, id, field) {
+    const key = this.keyBuilder.build(prefix, id);
+    const raw = await this.connection.getClient().hget(key, field);
+    if (raw === null) {
+      return null;
+    }
+    return this.serializer.deserialize(raw);
+  }
+  /**
+   * Serializes and writes one hash field.
+   *
+   * @typeParam T - The value's static type.
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id (the hash key).
+   * @param field - Hash field name (kept raw, never serialized).
+   * @param value - The value to store (passed through the serializer).
+   * @returns `1` when the field is new, `0` when it overwrote an existing field.
+   * @throws {CacheException} `SERIALIZATION_FAILED` when `value` cannot be encoded.
+   */
+  async hset(prefix, id, field, value) {
+    const key = this.keyBuilder.build(prefix, id);
+    return this.connection.getClient().hset(key, field, this.serializer.serialize(value));
+  }
+  /**
+   * Reads every field of a hash and deserializes each value.
+   *
+   * @typeParam T - The expected decoded type of every field value.
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id (the hash key).
+   * @returns A record of field → decoded value; `{}` when the hash does not exist.
+   * @throws {CacheException} `DESERIALIZATION_FAILED` when any field payload is
+   *   not decodable as `T`.
+   */
+  async hgetall(prefix, id) {
+    const key = this.keyBuilder.build(prefix, id);
+    const all = await this.connection.getClient().hgetall(key);
+    const entries = Object.entries(all).map(([field, raw]) => [
+      field,
+      this.serializer.deserialize(raw)
+    ]);
+    return Object.fromEntries(entries);
+  }
+  /**
+   * Deletes one or more hash fields.
+   *
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id (the hash key).
+   * @param fields - Field names to delete. No fields is a no-op (no Redis call).
+   * @returns The number of fields actually removed.
+   */
+  async hdel(prefix, id, ...fields) {
+    if (fields.length === 0) {
+      return 0;
+    }
+    const key = this.keyBuilder.build(prefix, id);
+    return this.connection.getClient().hdel(key, ...fields);
+  }
+  // ─── Set commands ──────────────────────────────────────────────────────────
+  /**
+   * Adds members to a set.
+   *
+   * Members are stored as raw strings — sets hold ids, not serialized objects,
+   * so the serializer is intentionally not applied here.
+   *
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id (the set key).
+   * @param members - String members to add. No members is a no-op (no Redis call).
+   * @returns The number of members newly added (excludes ones already present).
+   */
+  async sadd(prefix, id, ...members) {
+    if (members.length === 0) {
+      return 0;
+    }
+    return this.connection.getClient().sadd(this.keyBuilder.build(prefix, id), ...members);
+  }
+  /**
+   * Removes members from a set.
+   *
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id (the set key).
+   * @param members - String members to remove. No members is a no-op (no Redis call).
+   * @returns The number of members actually removed.
+   */
+  async srem(prefix, id, ...members) {
+    if (members.length === 0) {
+      return 0;
+    }
+    return this.connection.getClient().srem(this.keyBuilder.build(prefix, id), ...members);
+  }
+  /**
+   * Reads every member of a set.
+   *
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id (the set key).
+   * @returns The raw string members; `[]` when the set does not exist.
+   */
+  async smembers(prefix, id) {
+    return this.connection.getClient().smembers(this.keyBuilder.build(prefix, id));
+  }
+  /**
+   * Reports whether a member belongs to a set.
+   *
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id (the set key).
+   * @param member - The member to test.
+   * @returns `true` when the member is present, otherwise `false`.
+   */
+  async sismember(prefix, id, member) {
+    const result = await this.connection.getClient().sismember(this.keyBuilder.build(prefix, id), member);
+    return result === 1;
+  }
+  /**
+   * Reads the cardinality of a set.
+   *
+   * @param prefix - Entity-group prefix.
+   * @param id - Entity id (the set key).
+   * @returns The member count; `0` when the set does not exist.
+   */
+  async scard(prefix, id) {
+    return this.connection.getClient().scard(this.keyBuilder.build(prefix, id));
+  }
+  // ─── Iteration ─────────────────────────────────────────────────────────────
+  /**
+   * Lists keys matching a pattern under a prefix.
+   *
+   * WARNING: `KEYS` is O(N) and BLOCKS the Redis server for the whole scan —
+   * prefer {@link CacheService.scan} in production.
+   *
+   * @param prefix - Entity-group prefix.
+   * @param pattern - Glob pattern for the id segment, e.g. `'*'`.
+   * @returns The matching fully-namespaced keys.
+   * @example
+   * ```ts
+   * await cache.keys('users', '*') // ['app:users:u_1', 'app:users:u_2']
+   * ```
+   */
+  async keys(prefix, pattern) {
+    const fullPattern = this.keyBuilder.build(prefix, pattern);
+    return this.connection.getClient().keys(fullPattern);
+  }
+  /**
+   * Iterates keys matching a pattern under a prefix using a non-blocking cursor.
+   *
+   * Safe for production: `SCAN` never blocks the server. Standalone / sentinel
+   * only — Cluster exposes different scan semantics and is rejected.
+   *
+   * @param prefix - Entity-group prefix.
+   * @param pattern - Glob pattern for the id segment, e.g. `'*'`.
+   * @param count - Per-batch hint passed to `SCAN` (not a hard limit).
+   * @returns An async iterable of fully-namespaced keys.
+   * @throws {CacheException} `UNSUPPORTED_IN_CLUSTER` when called in cluster mode
+   *   (no usable top-level `scanStream`).
+   * @example
+   * ```ts
+   * for await (const key of cache.scan('users', '*')) {
+   *   // key === 'app:users:u_1'
+   * }
+   * ```
+   */
+  async *scan(prefix, pattern, count = SCAN_COUNT) {
+    const fullPattern = this.keyBuilder.build(prefix, pattern);
+    const client = this.connection.getClient();
+    if (!isScannableClient(client)) {
+      throw new CacheException(CACHE_ERROR_CODES.UNSUPPORTED_IN_CLUSTER, { operation: "scan" });
+    }
+    const stream = client.scanStream({ match: fullPattern, count });
+    for await (const chunk of stream) {
+      for (const key of chunk) {
+        yield key;
+      }
+    }
+  }
+  // ─── Pipeline / escape hatch ───────────────────────────────────────────────
+  /**
+   * Opens an ioredis pipeline for batching arbitrary commands.
+   *
+   * NOTE: keys passed to pipeline commands are NOT auto-namespaced — compose
+   * them through {@link KeyBuilder} yourself.
+   *
+   * @returns A chainable commander; call `.exec()` to flush.
+   * @example
+   * ```ts
+   * const pipe = cache.pipeline()
+   * pipe.set(keyBuilder.build('p', 'a'), '1')
+   * pipe.set(keyBuilder.build('p', 'b'), '2')
+   * await pipe.exec()
+   * ```
+   */
+  pipeline() {
+    return this.connection.getClient().pipeline();
+  }
+  /**
+   * Returns the raw ioredis client (escape hatch).
+   *
+   * Keys used through the returned client are NOT auto-namespaced. Reach for
+   * this only to run a command this facade does not expose.
+   *
+   * @returns The singleton ioredis client.
+   * @throws {CacheException} `UNSUPPORTED_IN_CLUSTER` when called in cluster
+   *   mode — `Cluster` does not share the full `Redis` API surface.
+   */
+  getClient() {
+    const client = this.connection.getClient();
+    if (!isScannableClient(client)) {
+      throw new CacheException(CACHE_ERROR_CODES.UNSUPPORTED_IN_CLUSTER, { operation: "getClient" });
+    }
+    return client;
+  }
+  // ─── Destructive maintenance ───────────────────────────────────────────────
+  /**
+   * Deletes EVERY key under the configured namespace via `SCAN` + `UNLINK`.
+   *
+   * Uses `UNLINK` (asynchronous reclaim) rather than `DEL` so a large keyset
+   * does not block the server. The `SCAN` pattern is scoped to
+   * `{namespace}{sep}*`, so keys of other namespaces are never touched.
+   *
+   * SAFETY: throws {@link CacheException} `FLUSH_DISABLED_IN_PRODUCTION` when
+   * `NODE_ENV === 'production'` unless `options.allowFlushInProduction` is `true`.
+   * Intended for tests and tooling — in production prefer
+   * {@link CacheService.del} / {@link CacheService.delMany}.
+   *
+   * @returns The total number of keys removed.
+   * @throws {CacheException} `FLUSH_DISABLED_IN_PRODUCTION` under the production guard.
+   * @throws {CacheException} `UNSUPPORTED_IN_CLUSTER` when called in cluster mode
+   *   (no usable top-level `scanStream`).
+   */
+  async flushNamespace() {
+    if (process.env["NODE_ENV"] === PRODUCTION_ENV && !this.options.allowFlushInProduction) {
+      throw new CacheException(CACHE_ERROR_CODES.FLUSH_DISABLED_IN_PRODUCTION);
+    }
+    const client = this.connection.getClient();
+    if (!isScannableClient(client)) {
+      throw new CacheException(CACHE_ERROR_CODES.UNSUPPORTED_IN_CLUSTER, {
+        operation: "flushNamespace"
+      });
+    }
+    const pattern = `${this.keyBuilder.getNamespacePrefix()}*`;
+    const stream = client.scanStream({ match: pattern, count: FLUSH_SCAN_COUNT });
+    let total = 0;
+    for await (const chunk of stream) {
+      const keys = chunk;
+      if (keys.length > 0) {
+        total += await client.unlink(...keys);
+      }
+    }
+    return total;
+  }
+  // ─── Lua scripts ───────────────────────────────────────────────────────────
+  /**
+   * Executes a Lua script registered with the {@link ScriptManagerService}. The
+   * `keys` are namespaced before reaching Redis (the same isolation guarantee as
+   * every other command); `args` are passed through untouched.
+   *
+   * @param scriptName - Name the script was registered under (via `options.scripts`
+   *   or `ScriptManagerService.register`).
+   * @param keys - `KEYS[]` (bare; namespaced here before execution).
+   * @param args - `ARGV[]` for the script.
+   * @returns The script's return value, typed `unknown` (Redis Lua is dynamic).
+   * @throws {CacheException} `SCRIPT_REGISTRY_MISSING` when no script manager is
+   *   wired (the module always wires one; this guards manual instantiations).
+   * @throws {CacheException} `SCRIPT_NOT_REGISTERED` / `SCRIPT_EXECUTION_FAILED`
+   *   propagated from the script manager.
+   * @example
+   * ```ts
+   * const swapped = (await cache.eval('compareAndSet', ['session:abc'], ['v1', 'v2'])) as number
+   * ```
+   */
+  async eval(scriptName, keys, args) {
+    if (!this.scriptRegistry) {
+      throw new CacheException(CACHE_ERROR_CODES.SCRIPT_REGISTRY_MISSING);
+    }
+    const namespacedKeys = keys.map((key) => this.keyBuilder.applyNamespace(key));
+    return this.scriptRegistry.eval(scriptName, namespacedKeys, args);
+  }
+  // ─── Health ────────────────────────────────────────────────────────────────
+  /**
+   * Reports whether Redis answers `PING`. Never throws — a connection failure
+   * resolves to `false`, making it safe to wire directly into a health endpoint
+   * (e.g. `@nestjs/terminus`).
+   *
+   * @returns `true` when the server replies `PONG`, otherwise `false`.
+   */
+  async isHealthy() {
+    try {
+      const pong = await this.connection.getClient().ping();
+      return pong === "PONG";
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Sends a raw `PING`. Unlike {@link CacheService.isHealthy}, this propagates a
+   * connection failure — use it when the caller wants to handle the error.
+   *
+   * @returns `'PONG'` on a healthy connection.
+   * @throws The underlying ioredis error when the connection is down.
+   */
+  async ping() {
+    return this.connection.getClient().ping();
+  }
+  /**
+   * Returns the Redis `INFO` output, optionally scoped to a single section.
+   *
+   * @param section - Optional section name (e.g. `'memory'`, `'clients'`,
+   *   `'replication'`); omit for the full report.
+   * @returns The `INFO` text.
+   */
+  async info(section) {
+    const client = this.connection.getClient();
+    return section === void 0 ? client.info() : client.info(section);
+  }
+};
+CacheService = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(BYMAX_CACHE_OPTIONS)),
+  __decorateParam(1, Inject(ConnectionManager)),
+  __decorateParam(2, Inject(KeyBuilder)),
+  __decorateParam(3, Optional()),
+  __decorateParam(3, Inject(BYMAX_CACHE_SERIALIZER)),
+  __decorateParam(4, Optional()),
+  __decorateParam(4, Inject(ScriptManagerService))
+], CacheService);
+var PubSubService = class {
+  /**
+   * @param options - Resolved module options. Supplies the serializer.
+   * @param connection - Owns the main client and mints subscriber connections.
+   *   Explicit `@Inject` — the published bundle is built without
+   *   emitDecoratorMetadata, so type-only DI cannot resolve a class provider
+   *   (CLAUDE.md §5).
+   * @param keyBuilder - Namespaces every channel/pattern.
+   * @param injectedSerializer - Optional `BYMAX_CACHE_SERIALIZER` provider.
+   * @param events - Optional consumer observability callback bag; a swallowed
+   *   handler/deserialization failure is forwarded to it instead of vanishing.
+   */
+  constructor(options, connection, keyBuilder, injectedSerializer, events) {
+    this.connection = connection;
+    this.keyBuilder = keyBuilder;
+    this.events = events;
+    /** Lazily-created dedicated subscriber connection (null until first subscribe). */
+    this.subscriber = null;
+    /** Live-listener ref-count per namespaced channel; UNSUBSCRIBE fires on the last. */
+    this.channelRefs = /* @__PURE__ */ new Map();
+    /** Live-listener ref-count per namespaced pattern; PUNSUBSCRIBE fires on the last. */
+    this.patternRefs = /* @__PURE__ */ new Map();
+    this.serializer = resolveSerializer(options, injectedSerializer);
+  }
+  /**
+   * Publishes a serialized message to a namespaced channel via the main client.
+   *
+   * @typeParam T - The message payload type.
+   * @param channel - Bare channel name (namespaced before publishing).
+   * @param message - Payload, encoded through the configured serializer.
+   * @returns The number of subscribers that received the message.
+   * @throws {CacheException} `SERIALIZATION_FAILED` when `message` cannot be encoded.
+   */
+  async publish(channel, message) {
+    const fullChannel = this.keyBuilder.applyNamespace(channel);
+    const raw = this.serializer.serialize(message);
+    return this.connection.getClient().publish(fullChannel, raw);
+  }
+  /**
+   * Subscribes to a namespaced channel. Opens the subscriber connection lazily;
+   * subsequent subscriptions reuse the same connection.
+   *
+   * The handler receives the deserialized message and the full namespaced
+   * channel. A throw inside the handler (or a malformed payload) is swallowed so
+   * it cannot tear down the shared subscriber.
+   *
+   * @typeParam T - The expected message payload type.
+   * @param channel - Bare channel name (namespaced before subscribing).
+   * @param handler - Invoked per message with `(message, channel)`.
+   * @returns An {@link Unsubscribe} that detaches THIS listener; the channel is
+   *   only UNSUBSCRIBE'd once its last listener is removed, so unsubscribing one
+   *   handler never breaks others subscribed to the same channel.
+   */
+  async subscribe(channel, handler) {
+    const fullChannel = this.keyBuilder.applyNamespace(channel);
+    const subscriber = this.ensureSubscriber();
+    const ref = await this.retainSubscription(
+      this.channelRefs,
+      fullChannel,
+      () => subscriber.subscribe(fullChannel)
+    );
+    const listener = (incoming, raw) => {
+      if (incoming !== fullChannel) {
+        return;
+      }
+      Promise.resolve().then(() => handler(this.serializer.deserialize(raw), incoming)).catch((error) => {
+        this.emitHandlerError(incoming, error);
+      });
+    };
+    subscriber.on("message", listener);
+    return this.makeUnsubscribe(
+      () => subscriber.off("message", listener),
+      () => this.releaseSubscription(
+        this.channelRefs,
+        fullChannel,
+        ref,
+        () => subscriber.unsubscribe(fullChannel)
+      )
+    );
+  }
+  /**
+   * Pattern-subscribes to a namespaced glob (e.g. `'users:*'`). Lazily opens the
+   * subscriber connection, shared with {@link PubSubService.subscribe}.
+   *
+   * @typeParam T - The expected message payload type.
+   * @param pattern - Bare glob pattern (namespaced before subscribing).
+   * @param handler - Invoked per message with `(message, channel, pattern)`,
+   *   both in their full namespaced form.
+   * @returns An {@link Unsubscribe} that detaches THIS listener; the pattern is
+   *   only PUNSUBSCRIBE'd once its last listener is removed.
+   */
+  async psubscribe(pattern, handler) {
+    const fullPattern = this.keyBuilder.applyNamespace(pattern);
+    const subscriber = this.ensureSubscriber();
+    const ref = await this.retainSubscription(
+      this.patternRefs,
+      fullPattern,
+      () => subscriber.psubscribe(fullPattern)
+    );
+    const listener = (matchedPattern, channel, raw) => {
+      if (matchedPattern !== fullPattern) {
+        return;
+      }
+      Promise.resolve().then(() => handler(this.serializer.deserialize(raw), channel, matchedPattern)).catch((error) => {
+        this.emitHandlerError(channel, error);
+      });
+    };
+    subscriber.on("pmessage", listener);
+    return this.makeUnsubscribe(
+      () => subscriber.off("pmessage", listener),
+      () => this.releaseSubscription(
+        this.patternRefs,
+        fullPattern,
+        ref,
+        () => subscriber.punsubscribe(fullPattern)
+      )
+    );
+  }
+  /** Closes the subscriber connection gracefully, forcing disconnect on failure. */
+  async onModuleDestroy() {
+    if (!this.subscriber) {
+      return;
+    }
+    const subscriber = this.subscriber;
+    this.subscriber = null;
+    try {
+      await subscriber.quit();
+    } catch {
+      subscriber.disconnect();
+    }
+  }
+  // ─── Private ───────────────────────────────────────────────────────────────
+  /**
+   * Returns the dedicated subscriber connection, creating it on first use.
+   *
+   * Reused for the lifetime of the module; ioredis transparently reconnects and
+   * re-subscribes, so a single connection is kept rather than recreated. Typed as
+   * the `Redis | Cluster` union the connection manager mints — `subscribe` /
+   * `psubscribe` exist on both, so no cast is needed (cluster Pub/Sub is an
+   * experimental passthrough per the spec).
+   */
+  ensureSubscriber() {
+    if (!this.subscriber) {
+      this.subscriber = this.connection.createSubscriberClient();
+    }
+    return this.subscriber;
+  }
+  /**
+   * Subscribes the target (channel or pattern) only when it gains its FIRST
+   * listener, then increments and returns its shared {@link SubscriptionRef} so a
+   * later release knows when to issue the matching UNSUBSCRIBE / PUNSUBSCRIBE.
+   *
+   * @param refs - The channel or pattern ref-count map.
+   * @param target - The full namespaced channel/pattern.
+   * @param subscribe - Issues the SUBSCRIBE / PSUBSCRIBE for `target`.
+   * @returns The shared ref for `target` (captured by the unsubscribe closure).
+   */
+  async retainSubscription(refs, target, subscribe) {
+    let ref = refs.get(target);
+    if (!ref) {
+      ref = { count: 0 };
+      refs.set(target, ref);
+      await subscribe();
+    }
+    ref.count += 1;
+    return ref;
+  }
+  /**
+   * Decrements the (closure-captured) ref and issues the UNSUBSCRIBE / PUNSUBSCRIBE
+   * only when the LAST listener is removed — so unsubscribing one handler never
+   * silently stops delivery to the others on the same channel/pattern.
+   *
+   * @param refs - The channel or pattern ref-count map.
+   * @param target - The full namespaced channel/pattern.
+   * @param ref - The shared ref returned by {@link retainSubscription}.
+   * @param unsubscribe - Issues the UNSUBSCRIBE / PUNSUBSCRIBE for `target`.
+   */
+  async releaseSubscription(refs, target, ref, unsubscribe) {
+    ref.count -= 1;
+    if (ref.count === 0) {
+      refs.delete(target);
+      await unsubscribe();
+    }
+  }
+  /**
+   * Builds an idempotent {@link Unsubscribe}: the first call detaches the listener
+   * and releases the subscription; later calls are no-ops, so a double unsubscribe
+   * cannot over-decrement a shared channel/pattern.
+   *
+   * @param detach - Removes this subscription's event listener.
+   * @param release - Decrements the reference count (see {@link releaseSubscription}).
+   */
+  makeUnsubscribe(detach, release) {
+    let released = false;
+    return async () => {
+      if (released) {
+        return;
+      }
+      released = true;
+      detach();
+      await release();
+    };
+  }
+  /**
+   * Forwards a swallowed handler / deserialization failure to the optional
+   * observability callback, itself swallowing any throw from `onEvent` — a
+   * faulty consumer (handler OR callback) must never tear down the subscriber.
+   * The error surfaces as an `'error'` event with `reason: 'handler_error'`.
+   *
+   * @param channel - The full namespaced channel the failed message arrived on.
+   * @param error - The caught handler / deserialization failure.
+   */
+  emitHandlerError(channel, error) {
+    try {
+      this.events?.onEvent?.("error", {
+        role: "subscriber",
+        reason: "handler_error",
+        channel,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    } catch {
+    }
+  }
+};
+PubSubService = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(BYMAX_CACHE_OPTIONS)),
+  __decorateParam(1, Inject(ConnectionManager)),
+  __decorateParam(2, Inject(KeyBuilder)),
+  __decorateParam(3, Optional()),
+  __decorateParam(3, Inject(BYMAX_CACHE_SERIALIZER)),
+  __decorateParam(4, Optional()),
+  __decorateParam(4, Inject(BYMAX_CACHE_EVENTS))
+], PubSubService);
+
+// src/server/bymax-cache.module.ts
+var BymaxCacheModule = class extends ConfigurableModuleClass {
+  /**
+   * Registers the cache module synchronously.
+   *
+   * @param options - Consumer options; validated and defaulted at registration.
+   * @returns The configured {@link DynamicModule}.
+   * @throws {import('./errors/cache.exception').CacheException} When the options
+   *   fail bootstrap validation (e.g. missing connection, misconfigured mode).
+   */
+  static forRoot(options) {
+    validateOptions(options);
+    const resolved = applyDefaults(options);
+    const providers = [
+      { provide: MODULE_OPTIONS_TOKEN, useValue: options },
+      { provide: BYMAX_CACHE_OPTIONS, useValue: resolved },
+      { provide: BYMAX_CACHE_EVENTS, useValue: resolved.events ?? null },
+      resolved.serializer ? { provide: BYMAX_CACHE_SERIALIZER, useValue: resolved.serializer } : { provide: BYMAX_CACHE_SERIALIZER, useClass: JsonSerializer },
+      ...BymaxCacheModule.buildCommonProviders()
+    ];
+    return {
+      module: BymaxCacheModule,
+      global: resolved.isGlobal,
+      providers,
+      exports: BymaxCacheModule.buildCommonExports()
+    };
+  }
+  /**
+   * Registers the cache module asynchronously, resolving its options through a
+   * consumer-supplied factory (e.g. reading from `ConfigService`).
+   *
+   * @remarks
+   * Delegates the async-options plumbing (the `MODULE_OPTIONS_TOKEN` factory,
+   * `inject`, `imports`, and the `global` flag) to the {@link ConfigurableModuleClass}
+   * base, then augments the produced module with the cache providers. Options are
+   * validated and defaulted INSIDE the `BYMAX_CACHE_OPTIONS` factory — which
+   * injects the base `MODULE_OPTIONS_TOKEN` — so a misconfiguration surfaces during
+   * bootstrap exactly as it does for {@link BymaxCacheModule.forRoot}. The events
+   * and serializer providers are factories deriving from the resolved options,
+   * since those values are not known until the async factory runs.
+   * @param options - Async registration options: a `useFactory` returning the
+   *   module options, plus optional `inject`, `imports`, and `isGlobal` (the
+   *   builder defaults `isGlobal` to `true`).
+   * @returns The configured {@link DynamicModule}.
+   * @throws {import('./errors/cache.exception').CacheException} During bootstrap,
+   *   when the factory-resolved options fail validation.
+   */
+  static forRootAsync(options) {
+    const base = super.forRootAsync(options);
+    const baseProviders = base.providers ?? [];
+    return {
+      ...base,
+      providers: [...baseProviders, ...BymaxCacheModule.buildAsyncProviders()],
+      exports: BymaxCacheModule.buildCommonExports()
+    };
+  }
+  /**
+   * The cache providers layered onto the base async module: the resolved-options
+   * provider (which validates + defaults the raw factory result read from
+   * `MODULE_OPTIONS_TOKEN`), the derived events and serializer providers, and the
+   * topology-independent {@link BymaxCacheModule.buildCommonProviders}. Mirrors the
+   * options/events/serializer wiring `forRoot` performs synchronously.
+   *
+   * @returns The async-only provider list.
+   */
+  static buildAsyncProviders() {
+    return [
+      {
+        provide: BYMAX_CACHE_OPTIONS,
+        useFactory: (raw) => {
+          validateOptions(raw);
+          return applyDefaults(raw);
+        },
+        inject: [MODULE_OPTIONS_TOKEN]
+      },
+      {
+        provide: BYMAX_CACHE_EVENTS,
+        useFactory: (resolved) => resolved.events ?? null,
+        inject: [BYMAX_CACHE_OPTIONS]
+      },
+      // Let Nest own the default serializer's lifecycle — matching forRoot's
+      // `useClass: JsonSerializer` — so the factory selects a consumer-supplied
+      // serializer over a container-managed default rather than `new`-ing one.
+      JsonSerializer,
+      {
+        provide: BYMAX_CACHE_SERIALIZER,
+        useFactory: (resolved, defaultSerializer) => resolved.serializer ?? defaultSerializer,
+        inject: [BYMAX_CACHE_OPTIONS, JsonSerializer]
+      },
+      ...BymaxCacheModule.buildCommonProviders()
+    ];
+  }
+  /**
+   * Topology-independent providers shared by `forRoot` and `forRootAsync` — the
+   * connection manager, key builder, cache services, and the `useExisting`
+   * aliases for the key-builder and script-registry tokens. The options, events,
+   * and serializer providers are NOT here: they differ between the sync
+   * (`useValue`) and async (`useFactory`) entry points.
+   *
+   * @returns The common provider list.
+   */
+  static buildCommonProviders() {
+    return [
+      ConnectionManager,
+      KeyBuilder,
+      CacheService,
+      PubSubService,
+      ScriptManagerService,
+      { provide: BYMAX_CACHE_KEY_BUILDER, useExisting: KeyBuilder },
+      { provide: BYMAX_CACHE_SCRIPT_REGISTRY, useExisting: ScriptManagerService },
+      { provide: BYMAX_CACHE_CONNECTION, useExisting: ConnectionManager }
+    ];
+  }
+  /**
+   * Tokens and services exported by both `forRoot` and `forRootAsync`.
+   *
+   * @returns The common export list.
+   */
+  static buildCommonExports() {
+    return [
+      BYMAX_CACHE_OPTIONS,
+      BYMAX_CACHE_CONNECTION,
+      BYMAX_CACHE_KEY_BUILDER,
+      BYMAX_CACHE_SCRIPT_REGISTRY,
+      BYMAX_CACHE_SERIALIZER,
+      ConnectionManager,
+      KeyBuilder,
+      CacheService,
+      PubSubService,
+      ScriptManagerService
+    ];
+  }
+};
+BymaxCacheModule = __decorateClass([
+  Module({})
+], BymaxCacheModule);
+
+// src/shared/constants/event-names.ts
+var CACHE_EVENT_NAMES = {
+  CONNECT: "connect",
+  READY: "ready",
+  ERROR: "error",
+  CLOSE: "close",
+  RECONNECTING: "reconnecting",
+  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, JsonSerializer, KeyBuilder, PubSubService, ScriptManagerService };