@bymax-one/nest-cache 1.0.0

package/dist/server/index.d.cts

@@ -0,0 +1,1296 @@
+import * as _nestjs_common from '@nestjs/common';
+import { Type, DynamicModule, ForwardReference, InjectionToken, OptionalFactoryDependency, OnModuleInit, OnModuleDestroy, OnApplicationBootstrap, HttpException, HttpStatus } from '@nestjs/common';
+import { ConnectionOptions } from 'node:tls';
+import { ClusterNode, ClusterOptions, SentinelAddress, NatMap, Redis, Cluster, ChainableCommander } from 'ioredis';
+export { ClusterNode, ClusterOptions, Redis, RedisKey, RedisOptions, SentinelAddress } from 'ioredis';
+
+/**
+ * Cache connection event types.
+ *
+ * Layer: shared — zero-dependency. Emitted by the connection manager and
+ * surfaced to consumers through the optional `events.onEvent` callback.
+ */
+/** Connection lifecycle events propagated from the underlying Redis client. */
+type CacheEventName = 'connect' | 'ready' | 'error' | 'close' | 'reconnecting' | 'end';
+/** Coarse connection status derived from the lifecycle events. */
+type CacheConnectionStatus = 'connecting' | 'ready' | 'reconnecting' | 'closed';
+
+/**
+ * Connection lifecycle observation contract.
+ *
+ * Layer: server. A consumer-supplied bag of callbacks the connection manager
+ * invokes on Redis lifecycle transitions. Used to bridge connection signals to
+ * a logger, metrics backend, or alerting system without coupling the library to
+ * any of them.
+ */
+
+/**
+ * Plug-in for connection lifecycle observation.
+ *
+ * Callbacks MUST be fast and non-blocking — any exception thrown is caught and
+ * swallowed by the connection manager (best-effort observability must never
+ * crash the connection lifecycle). Payloads carry no secret values.
+ */
+interface ICacheEvents {
+    /**
+     * Invoked on every connection lifecycle event.
+     *
+     * @remarks A forced disconnect during graceful shutdown surfaces here as an
+     *   `'error'` event carrying `{ role: 'main', reason: 'forced_disconnect' }`
+     *   (no `error` message field). The `CacheEventName` union has no dedicated
+     *   shutdown member, so branch on `data.reason` to tell a forced teardown apart
+     *   from an ioredis socket error (which carries an `error` string instead).
+     * @param event - The lifecycle event name.
+     * @param data - Secret-free structured context (e.g. `{ role: 'main' }`).
+     */
+    onEvent?: (event: CacheEventName, data: Record<string, unknown>) => void;
+}
+
+/**
+ * Lua script definition contract.
+ *
+ * Layer: server. Describes a named Lua script pre-registered with the script
+ * manager. The manager runs the register → `SCRIPT LOAD` → `EVALSHA` cycle,
+ * falling back to a full `EVAL` on `NOSCRIPT` (script evicted from the Redis
+ * cache).
+ */
+/**
+ * A named Lua script for atomic server-side operations.
+ *
+ * The `name` is the lookup key consumers pass to `eval`; the `lua` body is
+ * loaded once via `SCRIPT LOAD` and thereafter invoked by SHA via `EVALSHA`,
+ * with a transparent `NOSCRIPT` fallback.
+ */
+interface IScriptDefinition {
+    /** Unique lookup name used to invoke the script by reference. */
+    name: string;
+    /** The Lua source. Must never be built from untrusted input (CLAUDE.md §4). */
+    lua: string;
+}
+
+/**
+ * Value serialization strategy contract.
+ *
+ * Layer: server. Lets a consumer swap the default JSON serializer for a custom
+ * codec (e.g. MessagePack, a schema-aware encoder) without changing call sites.
+ */
+/**
+ * Strategy for serializing/deserializing cache values.
+ *
+ * Implementations MUST be deterministic and MUST throw on malformed input
+ * during `deserialize` — never return `undefined` or a partial value. The cache
+ * service catches that throw and wraps it as a `CacheException` so deserialization
+ * fails closed (security invariant — see CLAUDE.md §4).
+ */
+interface ISerializer {
+    /**
+     * Encodes a value to its string representation.
+     *
+     * @param value - The value to encode.
+     * @returns The serialized string.
+     * @throws If the value cannot be serialized.
+     */
+    serialize<T>(value: T): string;
+    /**
+     * Decodes a string back into a value.
+     *
+     * @param raw - The serialized string.
+     * @returns The decoded value, typed as `T`.
+     * @throws If `raw` is malformed (must fail closed, never return partial data).
+     */
+    deserialize<T>(raw: string): T;
+}
+
+/**
+ * Public configuration contracts for `BymaxCacheModule`.
+ *
+ * Layer: server. Describes every option a consumer passes to `forRoot` /
+ * `forRootAsync`, plus the mode-specific connection blocks. ioredis types are
+ * re-exported for consumer convenience. See `docs/technical_specification.md`
+ * §4 for full semantics.
+ */
+
+/**
+ * Standalone (single-node) connection settings.
+ *
+ * Either `url` OR `host` is required. When both are present, `url` wins —
+ * discrete fields act as fallback (spec §11.3).
+ */
+interface BymaxCacheStandaloneConnection {
+    /** `redis://` or `rediss://` (TLS) URL — overrides discrete fields. */
+    url?: string;
+    /** Hostname. Default: `localhost` when neither `url` nor `host` is set is rejected at validation. */
+    host?: string;
+    /** TCP port. Default: 6379. */
+    port?: number;
+    /** Auth password. Never logged or echoed in events. */
+    password?: string;
+    /** Logical database index. */
+    db?: number;
+    /** Auth username (Redis 6 ACLs). */
+    username?: string;
+    /** TLS options for `rediss://` or explicit TLS. */
+    tls?: ConnectionOptions;
+    /** Default: false (connects on `OnModuleInit`). */
+    lazyConnect?: boolean;
+    /** Default: 10_000 ms. */
+    connectTimeout?: number;
+    /** Default: 5_000 ms. */
+    commandTimeout?: number;
+    /** Default: 3. Do NOT pass `null` here — that value is BullMQ-specific. */
+    maxRetriesPerRequest?: number;
+    /** Default: true. */
+    enableReadyCheck?: boolean;
+    /** Default: false — fail fast instead of queueing. */
+    enableOfflineQueue?: boolean;
+    /** Default: `(times) => Math.min(times * 50, 2000)`. */
+    retryStrategy?: (times: number) => number | null | void;
+    /** Default: reconnects only on `READONLY` (replica failover). */
+    reconnectOnError?: (err: Error) => boolean | 1 | 2;
+    /** TCP keep-alive in ms. */
+    keepAlive?: number;
+    /** Disable Nagle's algorithm. */
+    noDelay?: boolean;
+    /** IP stack family. */
+    family?: 4 | 6;
+}
+/** Sentinel-mode connection settings. Required when `mode === 'sentinel'`. */
+interface BymaxCacheSentinelConnection {
+    /** Sentinel addresses to query for the current master. */
+    sentinels: SentinelAddress[];
+    /** Master group name configured in the sentinels. */
+    name: string;
+    /** Password for the sentinel nodes themselves. */
+    sentinelPassword?: string;
+    /** Password for the data nodes. */
+    password?: string;
+    /**
+     * Connect to the master or a replica.
+     * @remarks `'replica'` is the current Redis 7 terminology; `'slave'` is still
+     * accepted by ioredis 5 at the wire level for backwards compatibility but
+     * should be avoided in new code. Both values are accepted here and normalised
+     * to the ioredis wire value internally.
+     */
+    role?: 'master' | 'replica' | 'slave';
+    /**
+     * Rewrites the master/replica addresses the sentinels announce. Needed when the
+     * sentinels report addresses that are not reachable as-is from the client —
+     * e.g. a NAT'd Docker/Kubernetes network where the announced internal IP must
+     * be translated to a published host. Maps `'<announced-host>:<port>'` to the
+     * reachable `{ host, port }`.
+     */
+    natMap?: NatMap;
+}
+/** Cluster-mode connection settings. Required when `mode === 'cluster'`. */
+interface BymaxCacheClusterConnection {
+    /** Seed nodes for cluster discovery. */
+    nodes: ClusterNode[];
+    /** ioredis cluster options. */
+    options?: ClusterOptions;
+}
+/**
+ * Synchronous configuration for `BymaxCacheModule.forRoot()`.
+ *
+ * @see `docs/technical_specification.md` §4 for full semantics.
+ */
+interface BymaxCacheModuleOptions {
+    /** Connection mode. Default: `'standalone'`. */
+    mode?: 'standalone' | 'sentinel' | 'cluster';
+    /** Standalone connection block (used when `mode === 'standalone'`). */
+    connection?: BymaxCacheStandaloneConnection;
+    /** Sentinel connection block (used when `mode === 'sentinel'`). */
+    sentinel?: BymaxCacheSentinelConnection;
+    /** Cluster connection block (used when `mode === 'cluster'`). */
+    cluster?: BymaxCacheClusterConnection;
+    /** Global namespace prefix applied to every key. Default: `'app'`. */
+    namespace?: string;
+    /** Separator between namespace/prefix/id segments. Default: `':'`. */
+    keySeparator?: string;
+    /** Custom serializer. Default: `JsonSerializer`. */
+    serializer?: ISerializer;
+    /** Connection lifecycle event hooks — plug a logger or metrics sink here. */
+    events?: ICacheEvents;
+    /** Graceful shutdown timeout in ms. Default: 5000. */
+    shutdownTimeoutMs?: number;
+    /**
+     * Allows `flushNamespace()` to run even when `NODE_ENV === 'production'`.
+     * Default: false. SAFETY: leave false in real production environments.
+     */
+    allowFlushInProduction?: boolean;
+    /**
+     * Register the module as global. Default: true.
+     *
+     * @remarks Read by {@link BymaxCacheModule.forRoot}. For `forRootAsync` the
+     * `global` flag is decided synchronously — before the async factory resolves —
+     * so pass `isGlobal` at the `forRootAsync({ isGlobal, ... })` call site; an
+     * `isGlobal` returned from inside the async `useFactory` has no effect.
+     */
+    isGlobal?: boolean;
+    /** Lua scripts pre-registered at module init. */
+    scripts?: readonly IScriptDefinition[];
+}
+/**
+ * Async configuration for `BymaxCacheModule.forRootAsync()`.
+ * Standard NestJS dynamic-module async options shape.
+ *
+ * @remarks The recommended async-registration contract: a `useFactory` returning
+ * the module options. `forRootAsync`'s parameter is the builder-generated
+ * async-options type — a superset that also accepts NestJS's `useClass` /
+ * `useExisting` provider strategies — so this curated interface documents the
+ * common `useFactory` path most consumers use rather than redefining it.
+ */
+interface BymaxCacheModuleAsyncOptions {
+    /** Modules to import so the factory can inject their providers. */
+    imports?: Array<Type | DynamicModule | ForwardReference>;
+    /** Providers to inject into `useFactory`. */
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
+    /** Factory returning the resolved module options. */
+    useFactory: (...args: unknown[]) => Promise<BymaxCacheModuleOptions> | BymaxCacheModuleOptions;
+    /** Register the module as global. Default: true. */
+    isGlobal?: boolean;
+}
+
+/**
+ * Extra (non-option) registration flags folded into the generated dynamic
+ * module by the builder. Kept as a builder *extra* — rather than read from the
+ * resolved `BymaxCacheModuleOptions` — so the generated `forRootAsync` can decide
+ * the module's `global` flag synchronously, before the async options factory
+ * resolves.
+ */
+interface BymaxCacheModuleExtras {
+    /**
+     * Register the module globally. Required in the resolved extras (the builder
+     * fills it from the `{ isGlobal: true }` default) but optional for consumers,
+     * who receive it as `Partial<BymaxCacheModuleExtras>` on the registration types.
+     */
+    isGlobal: boolean;
+}
+declare const ConfigurableModuleClass: _nestjs_common.ConfigurableModuleCls<BymaxCacheModuleOptions, "forRoot", "create", BymaxCacheModuleExtras>;
+declare const OPTIONS_TYPE: BymaxCacheModuleOptions & Partial<BymaxCacheModuleExtras>;
+declare const ASYNC_OPTIONS_TYPE: _nestjs_common.ConfigurableModuleAsyncOptions<BymaxCacheModuleOptions, "create"> & Partial<BymaxCacheModuleExtras>;
+
+declare class BymaxCacheModule 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: typeof OPTIONS_TYPE): DynamicModule;
+    /**
+     * 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: typeof ASYNC_OPTIONS_TYPE): DynamicModule;
+    /**
+     * 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.
+     */
+    private static buildAsyncProviders;
+    /**
+     * 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.
+     */
+    private static buildCommonProviders;
+    /**
+     * Tokens and services exported by both `forRoot` and `forRootAsync`.
+     *
+     * @returns The common export list.
+     */
+    private static buildCommonExports;
+}
+
+/**
+ * Fully-resolved module options type.
+ *
+ * Layer: server. The shape produced by `applyDefaults` and stored under the
+ * `BYMAX_CACHE_OPTIONS` token. Defaulted fields (including `mode`) are always
+ * present; mode-specific blocks are kept as required-but-nullable so the
+ * resolver can assign them unconditionally under `exactOptionalPropertyTypes`,
+ * while consumers still narrow on `undefined`.
+ */
+
+/**
+ * Module options after defaults are merged. The defaulted fields
+ * (`mode`, `namespace`, `keySeparator`, `shutdownTimeoutMs`,
+ * `allowFlushInProduction`, `isGlobal`) are guaranteed present; the
+ * mode/connection blocks are present keys whose value may be `undefined`.
+ */
+type ResolvedOptions = Required<Pick<BymaxCacheModuleOptions, 'mode' | 'namespace' | 'keySeparator' | 'shutdownTimeoutMs' | 'allowFlushInProduction' | 'isGlobal'>> & {
+    connection: BymaxCacheModuleOptions['connection'];
+    sentinel: BymaxCacheModuleOptions['sentinel'];
+    cluster: BymaxCacheModuleOptions['cluster'];
+    serializer: BymaxCacheModuleOptions['serializer'];
+    events: BymaxCacheModuleOptions['events'];
+    scripts: BymaxCacheModuleOptions['scripts'];
+};
+
+/** The two client flavors this manager can produce. */
+type AnyRedis = Redis | Cluster;
+declare class ConnectionManager implements OnModuleInit, OnModuleDestroy {
+    private readonly options;
+    private readonly events?;
+    private client;
+    private readonly redisOptionsResolved;
+    /** Default backoff: grow 50 ms per attempt, capped at 2 s. */
+    private readonly defaultRetryStrategy;
+    /** Default reconnect policy: reconnect only on a `READONLY` replica failover. */
+    private readonly defaultReconnectOnError;
+    /**
+     * @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: ResolvedOptions, events?: ICacheEvents | undefined);
+    /** Opens the main client and waits for readiness unless `lazyConnect`. */
+    onModuleInit(): Promise<void>;
+    /**
+     * Returns the singleton main client, creating it on first access if the
+     * module init has not run yet.
+     *
+     * @returns The shared main client.
+     */
+    getClient(): AnyRedis;
+    /**
+     * 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(): AnyRedis;
+    /** Quits the main client gracefully, forcing `disconnect()` on timeout. */
+    onModuleDestroy(): Promise<void>;
+    /**
+     * 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.
+     */
+    private createClient;
+    /** Merges connection options with defaults; URL fields take precedence. */
+    private buildRedisOptions;
+    /** Forwards a lifecycle event to `events.onEvent`, swallowing consumer throws. */
+    private emit;
+    /** Wires lifecycle listeners that forward to `events.onEvent`, swallowing throws. */
+    private registerListeners;
+    /** Resolves once the client is ready; rejects (wrapped) on connection error. */
+    private waitUntilReady;
+}
+
+/**
+ * Composes Redis keys following `{namespace}{separator}{prefix}{separator}{id}`.
+ *
+ * With the defaults (`namespace='app'`, `separator=':'`):
+ * - `build('users', 'u_1')` → `'app:users:u_1'`
+ * - `applyNamespace('rl:u_1')` → `'app:rl:u_1'`
+ *
+ * @see `docs/technical_specification.md` §7 — Namespace Strategy
+ */
+declare class KeyBuilder {
+    private readonly namespace;
+    private readonly separator;
+    /**
+     * @param options - Resolved module options supplying the namespace + separator.
+     */
+    constructor(options: ResolvedOptions);
+    /**
+     * 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: string, id: string): string;
+    /**
+     * 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: string): string;
+    /**
+     * Returns the `{namespace}{separator}` prefix string used to build `SCAN`
+     * match patterns scoped to this namespace.
+     *
+     * @returns The namespace prefix, e.g. `'app:'`.
+     */
+    getNamespacePrefix(): string;
+}
+
+declare class ScriptManagerService implements OnApplicationBootstrap {
+    private readonly options;
+    private readonly connection;
+    /** Registry of script name → `{ lua, sha? }`. */
+    private readonly scripts;
+    /**
+     * @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: ResolvedOptions, connection: ConnectionManager);
+    /**
+     * 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.
+     */
+    onApplicationBootstrap(): Promise<void>;
+    /**
+     * 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: string, lua: string): void;
+    /**
+     * 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.
+     */
+    load(name: string): Promise<string>;
+    /**
+     * 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.
+     */
+    eval(name: string, keys: readonly string[], args: ReadonlyArray<string | number>): Promise<unknown>;
+}
+
+declare class CacheService {
+    private readonly options;
+    private readonly connection;
+    private readonly keyBuilder;
+    private readonly scriptRegistry?;
+    /** Resolved serializer: explicit option wins, then injected token, then JSON. */
+    private readonly serializer;
+    /**
+     * @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: ResolvedOptions, connection: ConnectionManager, keyBuilder: KeyBuilder, injectedSerializer?: ISerializer, scriptRegistry?: ScriptManagerService | undefined);
+    /**
+     * 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`.
+     */
+    get<T>(prefix: string, id: string): Promise<T | null>;
+    /**
+     * 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.
+     */
+    getRaw(prefix: string, id: string): Promise<string | null>;
+    /**
+     * 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.
+     */
+    set<T>(prefix: string, id: string, value: T, ttlSeconds?: number): Promise<void>;
+    /**
+     * 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.
+     */
+    setRaw(prefix: string, id: string, value: string, ttlSeconds?: number): Promise<void>;
+    /**
+     * 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.
+     */
+    setNx<T>(prefix: string, id: string, value: T, ttlSeconds?: number): Promise<boolean>;
+    /**
+     * Deletes a single key.
+     *
+     * @param prefix - Entity-group prefix.
+     * @param id - Entity id.
+     * @returns The number of keys removed (`0` or `1`).
+     */
+    del(prefix: string, id: string): Promise<number>;
+    /**
+     * 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.
+     */
+    delMany(prefix: string, ids: readonly string[]): Promise<number>;
+    /**
+     * Reports whether a key exists.
+     *
+     * @param prefix - Entity-group prefix.
+     * @param id - Entity id.
+     * @returns `true` when the key exists, otherwise `false`.
+     */
+    exists(prefix: string, id: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    incr(prefix: string, id: string, by?: number): Promise<number>;
+    /**
+     * 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.
+     */
+    decr(prefix: string, id: string, by?: number): Promise<number>;
+    /**
+     * 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.
+     */
+    expire(prefix: string, id: string, ttlSeconds: number): Promise<boolean>;
+    /**
+     * 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.
+     */
+    ttl(prefix: string, id: string): Promise<number>;
+    /**
+     * 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.
+     */
+    persist(prefix: string, id: string): Promise<boolean>;
+    /**
+     * 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`.
+     */
+    mget<T>(prefix: string, ids: readonly string[]): Promise<Array<T | null>>;
+    /**
+     * 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.
+     */
+    mset<T>(prefix: string, entries: ReadonlyArray<readonly [string, T]>): Promise<void>;
+    /**
+     * 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`.
+     */
+    hget<T>(prefix: string, id: string, field: string): Promise<T | null>;
+    /**
+     * 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.
+     */
+    hset<T>(prefix: string, id: string, field: string, value: T): Promise<number>;
+    /**
+     * 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`.
+     */
+    hgetall<T>(prefix: string, id: string): Promise<Record<string, T>>;
+    /**
+     * 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.
+     */
+    hdel(prefix: string, id: string, ...fields: readonly string[]): Promise<number>;
+    /**
+     * 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).
+     */
+    sadd(prefix: string, id: string, ...members: readonly string[]): Promise<number>;
+    /**
+     * 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.
+     */
+    srem(prefix: string, id: string, ...members: readonly string[]): Promise<number>;
+    /**
+     * 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.
+     */
+    smembers(prefix: string, id: string): Promise<string[]>;
+    /**
+     * 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`.
+     */
+    sismember(prefix: string, id: string, member: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    scard(prefix: string, id: string): Promise<number>;
+    /**
+     * 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']
+     * ```
+     */
+    keys(prefix: string, pattern: string): Promise<string[]>;
+    /**
+     * 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'
+     * }
+     * ```
+     */
+    scan(prefix: string, pattern: string, count?: number): AsyncIterable<string>;
+    /**
+     * 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(): ChainableCommander;
+    /**
+     * 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(): Redis;
+    /**
+     * 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`).
+     */
+    flushNamespace(): Promise<number>;
+    /**
+     * 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
+     * ```
+     */
+    eval(scriptName: string, keys: readonly string[], args: ReadonlyArray<string | number>): Promise<unknown>;
+    /**
+     * 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`.
+     */
+    isHealthy(): Promise<boolean>;
+    /**
+     * 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.
+     */
+    ping(): Promise<string>;
+    /**
+     * 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.
+     */
+    info(section?: string): Promise<string>;
+}
+
+/**
+ * `ISerializer` backed by `JSON.stringify` / `JSON.parse`.
+ *
+ * JSON limitations the consumer must account for:
+ * - `Date` becomes an ISO string — rehydrate on read if a `Date` is needed.
+ * - `Map`, `Set`, `BigInt`, and `undefined` are NOT preserved.
+ * - `Buffer` is encoded as a verbose `{ type: 'Buffer', data: [...] }` object.
+ *
+ * Consumers needing a structure-preserving codec (MessagePack, CBOR, protobuf)
+ * implement {@link ISerializer} directly — see the spec §6.3 MessagePack example.
+ *
+ * @example
+ * ```ts
+ * const s = new JsonSerializer()
+ * s.serialize({ a: 1 })          // '{"a":1}'
+ * s.deserialize<{ a: number }>('{"a":1}') // { a: 1 }
+ * ```
+ */
+declare class JsonSerializer implements ISerializer {
+    /**
+     * 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<T>(value: T): string;
+    /**
+     * 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<T>(raw: string): T;
+}
+
+/**
+ * Pub/Sub message handler contracts.
+ *
+ * Layer: server. Callback signatures the Pub/Sub service invokes when
+ * a message arrives on a subscribed channel or pattern. The message is already
+ * deserialized to `T` by the service.
+ */
+/**
+ * Handler for messages on an exactly-named channel.
+ *
+ * @typeParam T - The deserialized message payload type.
+ * @param message - The deserialized payload.
+ * @param channel - The channel the message arrived on.
+ */
+type IPubSubHandler<T> = (message: T, channel: string) => void | Promise<void>;
+/**
+ * Handler for messages on a pattern subscription (`psubscribe`).
+ *
+ * @typeParam T - The deserialized message payload type.
+ * @param message - The deserialized payload.
+ * @param channel - The concrete channel the message arrived on.
+ * @param pattern - The pattern that matched the channel.
+ */
+type IPubSubPatternHandler<T> = (message: T, channel: string, pattern: string) => void | Promise<void>;
+
+/** Detaches a subscription's listener and unsubscribes its channel/pattern. */
+type Unsubscribe = () => Promise<void>;
+declare class PubSubService implements OnModuleDestroy {
+    private readonly connection;
+    private readonly keyBuilder;
+    private readonly events?;
+    /** Lazily-created dedicated subscriber connection (null until first subscribe). */
+    private subscriber;
+    /** Live-listener ref-count per namespaced channel; UNSUBSCRIBE fires on the last. */
+    private readonly channelRefs;
+    /** Live-listener ref-count per namespaced pattern; PUNSUBSCRIBE fires on the last. */
+    private readonly patternRefs;
+    /** Resolved serializer: explicit option wins, then injected token, then JSON. */
+    private readonly serializer;
+    /**
+     * @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: ResolvedOptions, connection: ConnectionManager, keyBuilder: KeyBuilder, injectedSerializer?: ISerializer, events?: ICacheEvents | undefined);
+    /**
+     * 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.
+     */
+    publish<T>(channel: string, message: T): Promise<number>;
+    /**
+     * 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.
+     */
+    subscribe<T>(channel: string, handler: IPubSubHandler<T>): Promise<Unsubscribe>;
+    /**
+     * 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.
+     */
+    psubscribe<T>(pattern: string, handler: IPubSubPatternHandler<T>): Promise<Unsubscribe>;
+    /** Closes the subscriber connection gracefully, forcing disconnect on failure. */
+    onModuleDestroy(): Promise<void>;
+    /**
+     * 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).
+     */
+    private ensureSubscriber;
+    /**
+     * 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).
+     */
+    private retainSubscription;
+    /**
+     * 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`.
+     */
+    private releaseSubscription;
+    /**
+     * 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}).
+     */
+    private makeUnsubscribe;
+    /**
+     * 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.
+     */
+    private emitHandlerError;
+}
+
+/**
+ * NestJS injection tokens for `@bymax-one/nest-cache`.
+ *
+ * Layer: server. All tokens are `Symbol`-based to guarantee uniqueness across
+ * the NestJS DI graph — two consumers cannot collide on the same token by
+ * accident, and a string typo cannot resolve a foreign provider. Mirrors the
+ * pattern established by `@bymax-one/nest-auth` and `@bymax-one/nest-logger`.
+ */
+/** Resolved module options (connection, namespace, events, scripts). */
+declare const BYMAX_CACHE_OPTIONS: unique symbol;
+/**
+ * The connection manager holding the singleton ioredis client. Consumers can
+ * call `.getClient()` on the injected value to access the raw client. Wired as
+ * `useExisting: ConnectionManager` so it resolves to the same instance.
+ */
+declare const BYMAX_CACHE_CONNECTION: unique symbol;
+/** Registry of preloaded Lua scripts (name → SHA). */
+declare const BYMAX_CACHE_SCRIPT_REGISTRY: unique symbol;
+/** Optional consumer-supplied connection-event callback bag (`ICacheEvents`). */
+declare const BYMAX_CACHE_EVENTS: unique symbol;
+/** The value serializer (`ISerializer`; defaults to `JsonSerializer`). Injectable so consumers can override it. */
+declare const BYMAX_CACHE_SERIALIZER: unique symbol;
+/** The key builder that composes `{namespace}{sep}{prefix}{sep}{id}`. */
+declare const BYMAX_CACHE_KEY_BUILDER: unique symbol;
+
+/**
+ * Canonical cache error codes for `@bymax-one/nest-cache`.
+ *
+ * Layer: shared — zero-dependency, importable in any runtime (browser, edge,
+ * Node). The server subpath's `CacheException` maps these codes to messages and
+ * HTTP statuses.
+ */
+/**
+ * String error codes thrown by the cache library, namespaced under `cache.`.
+ *
+ * Append-only: new codes may be added, but existing values must never be
+ * renamed or removed without a major version bump — consumers switch on them.
+ */
+declare const CACHE_ERROR_CODES: {
+    readonly CONNECTION_FAILED: "cache.connection_failed";
+    readonly COMMAND_TIMEOUT: "cache.command_timeout";
+    readonly CONNECTION_LOST: "cache.connection_lost";
+    readonly SERIALIZATION_FAILED: "cache.serialization_failed";
+    readonly DESERIALIZATION_FAILED: "cache.deserialization_failed";
+    readonly INVALID_NAMESPACE: "cache.invalid_namespace";
+    readonly INVALID_KEY: "cache.invalid_key";
+    readonly SCRIPT_NOT_REGISTERED: "cache.script_not_registered";
+    readonly SCRIPT_EXECUTION_FAILED: "cache.script_execution_failed";
+    readonly SCRIPT_REGISTRY_MISSING: "cache.script_registry_missing";
+    readonly FLUSH_DISABLED_IN_PRODUCTION: "cache.flush_disabled_in_production";
+    readonly CLUSTER_MISCONFIGURED: "cache.cluster_misconfigured";
+    readonly SENTINEL_MISCONFIGURED: "cache.sentinel_misconfigured";
+    readonly SHUTDOWN_TIMEOUT: "cache.shutdown_timeout";
+    readonly UNSUPPORTED_IN_CLUSTER: "cache.unsupported_in_cluster";
+};
+/** Union of every cache error code string value. */
+type CacheErrorCode = (typeof CACHE_ERROR_CODES)[keyof typeof CACHE_ERROR_CODES];
+
+/**
+ * Server-side error code re-exports and human-readable messages.
+ *
+ * Layer: server. The canonical codes live in the zero-dependency shared subpath;
+ * this module re-exports them for server-side consumers and attaches the default
+ * English message catalog. A `Map` (not an index signature) backs the lookup so
+ * a runtime `code` value can never trigger object-injection.
+ */
+
+/**
+ * Default end-user-facing messages per error code (English; consumers localize
+ * upstream). Covers every code in {@link CACHE_ERROR_CODES}; unknown codes fall
+ * back to a generic message at the `CacheException` throw site.
+ *
+ * Exposed as a {@link ReadonlyMap} so a consumer cannot mutate the shared
+ * catalog — `.set`/`.delete`/`.clear` are compile errors. A `Map` (not an index
+ * signature) still backs it so a runtime `code` can never trigger object-injection.
+ */
+declare const CACHE_ERROR_MESSAGES: ReadonlyMap<CacheErrorCode, string>;
+
+/**
+ * Cache exception type and HTTP-status mapping.
+ *
+ * Layer: server — depends on `@nestjs/common` (`HttpException`). Error codes and
+ * messages live in `cache-error-codes`; this module maps codes to HTTP statuses
+ * and exposes the throwable. A `Map` (not an index signature) backs the status
+ * lookup so a runtime `code` can never trigger object-injection.
+ */
+
+/**
+ * Exception thrown by the cache library. Serializes to a structured
+ * `{ error: { code, message, details } }` body and carries an HTTP status, so it
+ * surfaces cleanly when thrown inside a NestJS request pipeline. The `code` and
+ * `details` are exposed as readonly fields for `catch`-block branching without a
+ * cast.
+ *
+ * SECURITY: `details` is serialized verbatim into the response body, so throw
+ * sites MUST keep it small and free of secret values (CLAUDE.md §4). The library
+ * does not truncate it here — a response-shaping exception filter is the right
+ * place for that and lands in a later phase.
+ *
+ * @example
+ * throw new CacheException(CACHE_ERROR_CODES.INVALID_KEY, { reason: 'empty_prefix' })
+ */
+declare class CacheException extends HttpException {
+    /** The canonical error code (one of {@link CACHE_ERROR_CODES}). */
+    readonly code: CacheErrorCode;
+    /** Structured, secret-free context attached at the throw site, or `null`. */
+    readonly details: Record<string, unknown> | null;
+    /**
+     * @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: CacheErrorCode, details?: Record<string, unknown>, statusCode?: HttpStatus);
+}
+
+/**
+ * Cache configuration value types.
+ *
+ * Layer: shared — zero-dependency. Semantic aliases used across the public API
+ * to make key-building intent explicit at call sites (spec §11.2, §D11/D17).
+ */
+/**
+ * A logical key namespace. Every key in an application shares one namespace,
+ * which guarantees tenant/app isolation — keys from one namespace never collide
+ * with another. Must be non-empty and must not contain the key separator.
+ *
+ * @example
+ * ```ts
+ * const namespace: CacheNamespace = 'app'        // single-app default
+ * const tenant: CacheNamespace = 'tenant-42'     // per-tenant isolation
+ * ```
+ */
+type CacheNamespace = string;
+/**
+ * A logical key prefix that groups related entities under a namespace. Combined
+ * by the key builder as `{namespace}{sep}{prefix}{sep}{id}`.
+ *
+ * @example
+ * ```ts
+ * const prefix: CacheKeyPrefix = 'user'      // → app:user:1
+ * const session: CacheKeyPrefix = 'session'  // → app:session:abc
+ * ```
+ */
+type CacheKeyPrefix = string;
+
+/**
+ * JSON-serializable value type.
+ *
+ * Layer: shared — zero-dependency. Describes exactly what the default
+ * `JsonSerializer` can round-trip through `JSON.stringify`/`JSON.parse`.
+ */
+/**
+ * A value that survives a JSON round-trip without loss.
+ *
+ * Deliberately excludes `Date`, `Map`, `Set`, `BigInt`, `undefined`, functions,
+ * and class instances — these either throw, silently drop, or change type under
+ * `JSON.stringify`. A consumer that needs them must supply a custom
+ * `ISerializer`; the typed `get<T>`/`set<T>` API does not constrain `T` to this
+ * type so a custom serializer stays unrestricted.
+ *
+ * @example
+ * ```ts
+ * const ok: SerializableValue = { id: 1, tags: ['a'], active: true, parent: null }
+ * // const bad: SerializableValue = { when: new Date() } // WRONG: Date is not serializable
+ * ```
+ */
+type SerializableValue = string | number | boolean | null | SerializableValue[] | {
+    [key: string]: SerializableValue;
+};
+
+/**
+ * Connection lifecycle event names, keyed by symbolic name. Each value is a
+ * {@link CacheEventName}; the `satisfies` clause keeps the object and the union
+ * in lock-step — adding an event to the union without a key here is a type error.
+ */
+declare const CACHE_EVENT_NAMES: {
+    readonly CONNECT: "connect";
+    readonly READY: "ready";
+    readonly ERROR: "error";
+    readonly CLOSE: "close";
+    readonly RECONNECTING: "reconnecting";
+    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, type ICacheEvents, type IPubSubHandler, type IPubSubPatternHandler, type IScriptDefinition, type ISerializer, JsonSerializer, KeyBuilder, PubSubService, ScriptManagerService, type SerializableValue, type Unsubscribe };