@loipv/nestjs-cache 0.0.0-stage → 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,1861 @@
+import { ModuleMetadata, FactoryProvider, NestInterceptor, ExecutionContext, CallHandler, DynamicModule } from '@nestjs/common';
+import { Reflector, HttpAdapterHost } from '@nestjs/core';
+import { Observable } from 'rxjs';
+
+/**
+ * Thrown for invalid configuration: bad decorator or module options, an unknown store name, or
+ * an invalid per-call argument.
+ */
+declare class CacheConfigError extends Error {
+    constructor(message: string);
+    /**
+     * The ESM and CommonJS builds each define this class, so `instanceof` also accepts any `Error`
+     * named `CacheConfigError`. Subclasses keep the normal prototype check.
+     */
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+
+/**
+ * A cache key: a template rendered against the method arguments (`'user:{0}'`, `'{0.id}'`), or
+ * a callback of the arguments. Without one, the key is built from all the arguments.
+ */
+type KeySpec<A extends unknown[]> = string | ((...args: A) => string);
+/**
+ * The tags of a cached method (spec 2.1): templates with the key syntax (`'{0}'`, `'{0.id}'`),
+ * rendered against the call's arguments, or a callback of the result then the arguments.
+ */
+type TagSpec<A extends unknown[], R> = readonly string[] | ((result: R, ...args: A) => readonly string[]);
+/** The tags `@CacheEvict` invalidates: templates over the arguments, or a callback of them. */
+type EvictTagSpec<A extends unknown[]> = readonly string[] | ((...args: A) => readonly string[]);
+/**
+ * The expiry strategy of a call that does not load (`@CachePut`, `set`, `setMany`, `get`,
+ * `getMany`): `'fixed'` (the default), `'swr'` with `staleTtl` (ms an entry is served stale
+ * after `ttl`), or `'sliding'` with an optional `maxTtl` cap (ms). `softTimeout` is not
+ * supported here; see `LoadStrategyOptions`.
+ */
+type StrategyOptions = {
+    strategy?: 'fixed';
+    staleTtl?: never;
+    maxTtl?: never;
+    softTimeout?: never;
+} | {
+    strategy: 'swr';
+    staleTtl: number;
+    maxTtl?: never;
+    softTimeout?: never;
+} | {
+    strategy: 'sliding';
+    maxTtl?: number;
+    staleTtl?: never;
+    softTimeout?: never;
+};
+/**
+ * The expiry strategy of a call that loads (`@Cacheable`, `@HttpCache`, `getOrSet`,
+ * `getOrSetMany`): `StrategyOptions` plus `softTimeout` (swr only). On a stale hit, wait up to
+ * `softTimeout` ms for the background refresh and return its value if it lands in time, else
+ * the stale one.
+ */
+type LoadStrategyOptions = {
+    strategy?: 'fixed';
+    staleTtl?: never;
+    maxTtl?: never;
+    softTimeout?: never;
+} | {
+    strategy: 'swr';
+    staleTtl: number;
+    maxTtl?: never;
+    softTimeout?: number;
+} | {
+    strategy: 'sliding';
+    maxTtl?: number;
+    staleTtl?: never;
+    softTimeout?: never;
+};
+interface TargetOptions {
+    namespace?: string;
+    store?: string;
+}
+interface WritePolicy$1<C extends unknown[], R> {
+    ttl?: number;
+    cacheNull?: boolean;
+    nullTtl?: number;
+    condition?: (...args: C) => boolean;
+    unless?: (result: R) => boolean;
+}
+/**
+ * Options of `@Cacheable`. `K`, `C` and `G` are the argument lists the `key`, `condition` and
+ * `tags` callbacks declare; `R` is the method's resolved result.
+ */
+type CacheableOptions<K extends unknown[], C extends unknown[], R, G extends unknown[] = never[]> = TargetOptions & LoadStrategyOptions & WritePolicy$1<C, R> & {
+    key?: KeySpec<K>;
+    lock?: boolean;
+    tags?: TagSpec<G, R>;
+};
+/** Options of `@CachePut`: those of `@Cacheable` without `lock` and `softTimeout`. */
+type CachePutOptions<K extends unknown[], C extends unknown[], R, G extends unknown[] = never[]> = TargetOptions & StrategyOptions & WritePolicy$1<C, R> & {
+    key?: KeySpec<K>;
+    tags?: TagSpec<G, R>;
+};
+/**
+ * Options of `@CacheEvict`: evict `key` (one spec or several) and invalidate `tags`, or clear
+ * the whole `namespace` with `allEntries: true`. `beforeInvocation: true` evicts before the
+ * method runs; by default eviction follows a successful call.
+ */
+type CacheEvictOptions<A extends unknown[], G extends unknown[] = never[]> = (TargetOptions & {
+    key?: KeySpec<A> | readonly KeySpec<A>[];
+    allEntries?: false;
+    beforeInvocation?: boolean;
+    tags?: EvictTagSpec<G>;
+}) | {
+    namespace: string;
+    store?: string;
+    allEntries: true;
+    key?: never;
+    beforeInvocation?: boolean;
+    tags?: EvictTagSpec<G>;
+};
+type MethodFn<A extends unknown[], R> = (...args: [...A, ...never[]]) => Promise<R>;
+/** `G` is the argument list a tags callback declares; it is checked like `K` and `C`. */
+type AsyncMethodDecorator<K extends unknown[], C extends unknown[], R, G extends unknown[] = never[]> = <T extends MethodFn<K, R> & MethodFn<C, R> & MethodFn<G, R>>(target: object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => void;
+
+/**
+ * Caches the result of an async method: a hit returns the cached value without running the
+ * method; a miss runs it and stores the result. Invalid options throw `CacheConfigError` at
+ * class definition.
+ */
+declare function Cacheable<K extends unknown[] = never[], C extends unknown[] = never[], R = unknown, G extends unknown[] = never[]>(options?: CacheableOptions<K, C, R, G>): AsyncMethodDecorator<K, C, R, G>;
+
+/**
+ * Always runs the async method and writes its result to the cache (unless `condition` is false
+ * or `unless` is true). Invalid options throw `CacheConfigError` at class definition.
+ */
+declare function CachePut<K extends unknown[] = never[], C extends unknown[] = never[], R = unknown, G extends unknown[] = never[]>(options?: CachePutOptions<K, C, R, G>): AsyncMethodDecorator<K, C, R, G>;
+
+/**
+ * Evicts cache entries around an async method: keys, tags or a whole namespace, after the
+ * method succeeds (or before it, with `beforeInvocation`). Eviction failures never reject the
+ * call. Invalid options throw `CacheConfigError` at class definition.
+ */
+declare function CacheEvict<K extends unknown[] = never[], G extends unknown[] = never[]>(options?: CacheEvictOptions<K, G>): AsyncMethodDecorator<K, never[], unknown, G>;
+
+/** The state of a `CircuitBreakerStore`, as `breaker` events report it. */
+type BreakerState = 'closed' | 'open' | 'half-open';
+/** How much the library logs: nothing, errors and warnings (the default), or also one debug line per event. */
+type CacheLogLevel = 'off' | 'error' | 'debug';
+/**
+ * The operation an `error` event reports as failed.
+ *
+ * Provided by the library. New members, events, fields or values may be added in a minor release;
+ * handle unknown ones.
+ */
+type CacheOperation = 'get' | 'set' | 'delete' | 'clear' | 'deserialize' | 'key' | 'publish' | 'subscribe' | 'refresh' | 'lock' | 'version'
+/** An invalid tag list (a throwing tag callback included); the entry is not written. */
+ | 'tag';
+/**
+ * The payload of each `CacheEvents` event. `store` is the store name; `key` and `keys` are the
+ * user keys, without the prefix, namespace or version token.
+ *
+ * Provided by the library. New members, events, fields or values may be added in a minor release;
+ * handle unknown ones.
+ */
+interface CacheEventMap {
+    /** A read found the entry; `stale` is an `swr` entry past its `ttl`. */
+    hit: {
+        store: string;
+        namespace: string | undefined;
+        key: string;
+        stale: boolean;
+    };
+    miss: {
+        store: string;
+        namespace: string | undefined;
+        key: string;
+    };
+    set: {
+        store: string;
+        namespace: string | undefined;
+        key: string;
+        /**
+         * The TTL the store was given, in ms: under `swr` it includes `staleTtl`, and it carries the
+         * `defaults.jitter` (not under `sliding`).
+         */
+        ttl: number;
+    };
+    delete: {
+        store: string;
+        namespace: string | undefined;
+        /** The user keys deleted, as passed (not the store keys). */
+        keys: readonly string[];
+    };
+    clear: {
+        store: string;
+        namespace: string;
+    };
+    /** One loader call finished (`success: false` when it threw). */
+    load: {
+        store: string;
+        namespace: string | undefined;
+        /** The loaded key; on a batch load, the first of `keys`. */
+        key: string;
+        /** Only on a batch load (`getOrSetMany`): every key passed to the loader; `key` is the first. */
+        keys?: readonly string[];
+        durationMs: number;
+        success: boolean;
+    };
+    /** A cache failure the call did not surface; see `CacheOperation`. */
+    error: {
+        store: string;
+        operation: CacheOperation;
+        error: unknown;
+    };
+    lock: {
+        store: string;
+        namespace: string | undefined;
+        key: string;
+        waitedMs: number;
+        acquired: boolean;
+    };
+    breaker: {
+        store: string;
+        state: BreakerState;
+    };
+}
+/**
+ * What a store gets from `CacheStore.bind`: it reports its own failures (`error`) and breaker
+ * state changes (`breaker`) through it; the module adds the store name.
+ *
+ * Provided by the library. New members, events, fields or values may be added in a minor release;
+ * handle unknown ones.
+ */
+interface CacheEventSink {
+    emit(event: 'error', payload: {
+        operation: CacheOperation;
+        error: unknown;
+    }): void;
+    emit(event: 'breaker', payload: {
+        state: BreakerState;
+    }): void;
+    /**
+     * The module's log level, so a store can skip its own warnings at `'off'`. Sinks from
+     * `CacheModule` always set it; a missing value (a hand-built sink) means `'error'`.
+     */
+    readonly logLevel?: CacheLogLevel;
+}
+type Listener<E extends keyof CacheEventMap> = (payload: CacheEventMap[E]) => void;
+/**
+ * The cache event bus, provided by `CacheModule`: inject it and subscribe with `on`. Only the
+ * library emits events.
+ *
+ * Created by Nest; inject it, do not construct it. Constructor parameters are not part of the
+ * public API.
+ */
+declare class CacheEvents {
+    private readonly onListenerError?;
+    private readonly listeners;
+    constructor(onListenerError?: ((error: unknown) => void) | undefined);
+    /**
+     * Calls `listener` with the payload of every `event`, synchronously, in registration order.
+     * A listener that throws is isolated: the module logs it (unless `logging.level` is `'off'`)
+     * and it never reaches the cache call. Returns a function that removes this registration.
+     */
+    on<E extends keyof CacheEventMap>(event: E, listener: Listener<E>): () => void;
+}
+
+/** What the engine stores per entry; a `Serializer` turns it into the stored string. */
+interface CacheEnvelope {
+    /** The envelope format version. */
+    v: 1;
+    /** The cached value; `null` when `nil` is set. */
+    value: unknown;
+    /** When the entry was written, in ms since the epoch. */
+    storedAt: number;
+    /** When the entry expires (ms since the epoch); under `swr`, when its stale window ends. */
+    expiresAt?: number;
+    /** `swr` only: when the entry turns stale (ms since the epoch); it is fresh before. */
+    staleAt?: number;
+    /** Set on a stored empty value (`cacheNull`): which one it was, as `value` is `null`. */
+    nil?: 'null' | 'undefined';
+    /** The tag versions the entry was written with, tag to token; absent on an untagged entry. */
+    tags?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Turns an entry's envelope into the string a store holds, and back
+ * (`CacheModuleOptions.serializer`).
+ * `deserialize` must throw on input it does not recognise: the engine reports that as an `error`
+ * event with operation `'deserialize'` and treats the entry as a miss.
+ *
+ * `deserialize(serialize(e))` must keep every field of `e`, including fields this version does
+ * not know.
+ *
+ * Implemented by you. In 1.x, members are only added as optional, and the library checks that
+ * they exist before calling them.
+ */
+interface Serializer {
+    serialize(envelope: CacheEnvelope): string;
+    deserialize(raw: string): CacheEnvelope;
+}
+/** The default serializer: `JSON.stringify` and `JSON.parse`, with an envelope shape check. */
+declare const jsonSerializer: Serializer;
+
+/**
+ * A message announcing that keys were written or removed on one instance.
+ * Receivers drop the matching entries from their local (L1) cache.
+ *
+ * `origin` identifies the publishing instance, so receivers can ignore their
+ * own messages. A message carries either exact `keys` or a `prefix`.
+ *
+ * Provided by the library. New members, events, fields or values may be added in a minor release;
+ * handle unknown ones.
+ *
+ * A bus passes messages through as opaque JSON.
+ */
+type InvalidationMessage = {
+    origin: string;
+    keys: readonly string[];
+} | {
+    origin: string;
+    prefix: string;
+};
+/**
+ * Cross-instance channel that keeps local caches in sync (for example Redis
+ * Pub/Sub, NATS or Kafka). It only affects the freshness of L1 entries; the
+ * data in the shared store is always correct.
+ *
+ * Implemented by you. In 1.x, members are only added as optional, and the library checks that
+ * they exist before calling them.
+ */
+interface InvalidationBus {
+    /** Broadcasts a message to every subscribed instance. */
+    publish(message: InvalidationMessage): Promise<void>;
+    /**
+     * Registers the handler that receives messages from the channel. If it rejects, the bus
+     * should keep trying to subscribe (for example when its connection becomes ready), and a
+     * later call should retry rather than return the same rejection.
+     */
+    subscribe(handler: (message: InvalidationMessage) => void): Promise<void>;
+    /**
+     * Registers a handler called after the connection is re-established, or after a
+     * subscription that had failed is established later. Messages may have been missed
+     * meanwhile, so receivers clear their L1.
+     */
+    onReconnect(handler: () => void): void;
+    /**
+     * Optional. Registers a handler for errors the bus handles internally, such as a lost
+     * subscriber connection or a failed re-subscribe. `TieredStore` reports them as `error`
+     * events with `operation: 'subscribe'`. Handlers must not throw.
+     */
+    onError?(handler: (error: unknown) => void): void;
+    /** Releases the bus connection. Called at shutdown; must be idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Distributed mutual exclusion, used by the cache engine to avoid stampedes across instances.
+ *
+ * Implemented by you. In 1.x, members are only added as optional, and the library checks that
+ * they exist before calling them.
+ */
+interface LockProvider {
+    /**
+     * Tries to take the lock for `key`, the complete lock key the engine computed (the provider adds nothing to it), for at most `ttlMs` milliseconds (integer >= 1). Returns a
+     * handle when acquired, or `undefined` when the lock is held by someone else. Never waits.
+     */
+    acquire(key: string, ttlMs: number): Promise<LockHandle | undefined>;
+}
+/**
+ * Proof of ownership of an acquired lock.
+ *
+ * Implemented by you. In 1.x, members are only added as optional, and the library checks that
+ * they exist before calling them.
+ */
+interface LockHandle {
+    /**
+     * Releases the lock only if it is still ours (it may have expired and been taken by another
+     * owner). A second call is a no-op.
+     */
+    release(): Promise<void>;
+}
+/**
+ * Contract for a cache backend. Values are opaque serialized strings.
+ *
+ * Implemented by you. In 1.x, members are only added as optional, and the library checks that
+ * they exist before calling them.
+ */
+interface CacheStore {
+    /** Returns the stored string, or `undefined` for a miss or an expired entry. */
+    get(key: string): Promise<string | undefined>;
+    /**
+     * Stores `value` under `key`.
+     *
+     * @param ttlMs Time to live in milliseconds; always an integer >= 1.
+     */
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    /** Removes the given keys. Deleting an unknown key is a no-op. */
+    delete(keys: readonly string[]): Promise<void>;
+    /**
+     * Removes every key that starts with `prefix`. An empty prefix (`''`)
+     * removes everything.
+     */
+    clear(prefix: string): Promise<void>;
+    /**
+     * Optional. Reads the entry and resets its TTL to `ttlMs` in one step
+     * (milliseconds, integer >= 1). Returns `undefined` for a miss. Used by the `sliding` strategy. The memory and Redis stores are atomic; a
+     * tiered store refreshes the window on L1 misses only.
+     * Stores should implement it: when it is missing, the engine falls back to `get` followed by a
+     * `set`, which is not atomic.
+     */
+    getAndTouch?(key: string, ttlMs: number): Promise<string | undefined>;
+    /**
+     * Optional. Reads several keys at once. The result has one element per key, in the same order,
+     * `undefined` for a miss or an expired entry. An empty list resolves `[]` without any command.
+     * When missing, callers fall back to one `get` per key.
+     */
+    getMany?(keys: readonly string[]): Promise<(string | undefined)[]>;
+    /**
+     * Optional. Stores several entries at once; each `ttlMs` is an integer >= 1. An empty list
+     * resolves without any command. When missing, callers fall back to one `set` per entry.
+     */
+    setMany?(entries: readonly {
+        key: string;
+        value: string;
+        ttlMs: number;
+    }[]): Promise<void>;
+    /**
+     * Optional. Like `get`, but rejects instead of degrading when the durable tier cannot be read.
+     * Stores whose `get` already rejects on failure (memory, Redis) need not implement it.
+     * Implementing it also opts the store into the version-token fallback (a failed version read
+     * reuses the last token this process knew).
+     */
+    getStrict?(key: string): Promise<string | undefined>;
+    /**
+     * Optional. Like `set`, but rejects unless the durable tier stored the value.
+     * Stores whose `set` already rejects on failure need not implement it.
+     */
+    setStrict?(key: string, value: string, ttlMs: number): Promise<void>;
+    /**
+     * Optional. Distributed lock backed by this store. Absent when the store cannot lock; the
+     * engine then falls back to a per-process lock.
+     */
+    readonly lock?: LockProvider;
+    /**
+     * Optional bus that `TieredStore` uses to sync L1 caches when this store is
+     * the L2.
+     */
+    readonly invalidation?: InvalidationBus;
+    /**
+     * Optional. Called once at module init with a sink scoped to this store's
+     * name, so the store can report errors it handles internally.
+     */
+    bind?(events: CacheEventSink): void;
+    /**
+     * Optional. Health probe used by `CacheHealthIndicator`: resolves when the store is
+     * reachable and rejects otherwise. Absent when the store cannot be probed.
+     */
+    ping?(): Promise<void>;
+    /** Optional. Called at shutdown to release resources; must be idempotent. */
+    close?(): Promise<void>;
+}
+
+/** `defaults.lock`: the distributed lock taken on a miss, for stores that have one. */
+interface CacheLockDefaults {
+    /**
+     * Whether `getOrSet`, `@Cacheable` and `@HttpCache` lock by default; a call's `lock` overrides
+     * it. Default `false`.
+     */
+    enabled?: boolean;
+    /** How long a lock is held at most, in ms. Default 10 000. */
+    ttl?: number;
+    /**
+     * How long a caller that did not get the lock waits for the holder's value, in ms; then it
+     * loads without the lock. Default 3 000.
+     */
+    waitTimeout?: number;
+    /** Delay between two re-reads of the entry while waiting, in ms. Default 50. */
+    retryDelay?: number;
+}
+/** `defaults`: what a call or decorator that does not set an option uses. */
+interface CacheDefaults {
+    /** Entry TTL in ms. Default 60 000. */
+    ttl?: number;
+    /** Random TTL spread: `ttl x (1 + r)`, `r` in `[-jitter, +jitter]`; in `[0, 1)`. Default 0. */
+    jitter?: number;
+    /** Whether `null` and `undefined` results are stored. Default `false`. */
+    cacheNull?: boolean;
+    /** TTL of a stored empty value, in ms. Default 30 000. */
+    nullTtl?: number;
+    lock?: CacheLockDefaults;
+}
+/** Options of `CacheModule.forRoot`, and the value `forRootAsync`'s `useFactory` resolves. */
+interface CacheModuleOptions {
+    /** Prepended to every key as `<prefix>:`. Default none. */
+    prefix?: string;
+    /**
+     * Named stores; `default` is required when `stores` is set. Default
+     * `{ default: memoryStore() }`.
+     */
+    stores?: {
+        default: CacheStore;
+        [name: string]: CacheStore;
+    };
+    defaults?: CacheDefaults;
+    /** Turns entry envelopes into the strings stores hold. Default `jsonSerializer`. */
+    serializer?: Serializer;
+    /** `level` defaults to `'error'`. */
+    logging?: {
+        level?: CacheLogLevel;
+    };
+    /**
+     * Percent-encodes `%` and `:` in string and number arguments rendered into template keys.
+     * Defaults to `false`; key callbacks are never escaped.
+     */
+    escapeKeyArgs?: boolean;
+    /**
+     * Namespaces with `versioned: true` get O(1) `clear` through a version token in their keys.
+     * Matching is exact: a sub-namespace such as `users:admin` does not follow a versioned `users`.
+     */
+    namespaces?: {
+        [namespace: string]: {
+            versioned?: boolean;
+        };
+    };
+    /** `cacheTtl` (ms, default 1000) is how long a version token is cached in this process. */
+    versioning?: {
+        cacheTtl?: number;
+    };
+}
+/** Options of `CacheModule.forRootAsync`: `useFactory` resolves the `CacheModuleOptions`. */
+interface CacheModuleAsyncOptions {
+    /** Registers the module globally. Default `false`. */
+    isGlobal?: boolean;
+    imports?: ModuleMetadata['imports'];
+    inject?: FactoryProvider['inject'];
+    useFactory: (...args: never[]) => CacheModuleOptions | Promise<CacheModuleOptions>;
+}
+interface ResolvedDefaults {
+    ttl: number;
+    jitter: number;
+    cacheNull: boolean;
+    nullTtl: number;
+    lock: {
+        enabled: boolean;
+        ttl: number;
+        waitTimeout: number;
+        retryDelay: number;
+    };
+}
+interface ResolvedCacheOptions {
+    prefix: string | undefined;
+    stores: ReadonlyMap<string, CacheStore>;
+    defaults: ResolvedDefaults;
+    serializer: Serializer;
+    logging: {
+        level: CacheLogLevel;
+    };
+    escapeKeyArgs: boolean;
+    versionedNamespaces: ReadonlySet<string>;
+    versionCacheTtl: number;
+}
+
+/** A span attribute value the library sets: a string, number, boolean or list of strings. */
+type SpanAttributeValue = string | number | boolean | string[];
+/**
+ * Structural subset of an OpenTelemetry `SpanContext`: what a link needs to point at a span.
+ * Satisfied by the result of `span.spanContext()` in the OpenTelemetry JS API 1.x.
+ *
+ * Satisfied by the client you pass in. In 1.x, members are only added as optional, and the
+ * library checks that they exist before calling them.
+ */
+interface SpanContextLike {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+}
+/**
+ * Structural subset of an OpenTelemetry `Span`: only the methods the library calls. Satisfied by
+ * the spans of the OpenTelemetry JS API 1.x, so no dependency on that package is needed.
+ *
+ * Satisfied by the client you pass in. In 1.x, members are only added as optional, and the
+ * library checks that they exist before calling them.
+ */
+interface SpanLike {
+    /** Sets one attribute (`cache.store`, `cache.result`, ...). */
+    setAttribute(key: string, value: SpanAttributeValue): unknown;
+    /** Adds an event; the library adds `cache.error` with `cache.error.operation` on a swallowed error. */
+    addEvent(name: string, attributes?: Record<string, SpanAttributeValue>): unknown;
+    /** Records an error: one the caller receives, or one the library swallowed. */
+    recordException(exception: unknown): void;
+    /** Sets the status; the library only sets `{ code: 2 }` (`ERROR`) for an error the caller receives. */
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    /** Ends the span; the library calls it exactly once per span it starts. */
+    end(): void;
+    /** The span's identity, used to link a background `cache.refresh` to the span that started it. */
+    spanContext(): SpanContextLike;
+}
+/**
+ * Structural subset of an OpenTelemetry `SpanOptions`: the options the library passes.
+ *
+ * Satisfied by the client you pass in. In 1.x, members are only added as optional, and the
+ * library checks that they exist before calling them.
+ */
+interface SpanOptionsLike {
+    /** Attributes set when the span starts. */
+    attributes?: Record<string, SpanAttributeValue>;
+    /** `true` starts a new trace (the background `cache.refresh` span). */
+    root?: boolean;
+    /** Links to related spans (`cache.refresh` links to the span that triggered it). */
+    links?: {
+        context: SpanContextLike;
+    }[];
+}
+/**
+ * Structural subset of an OpenTelemetry `Tracer`. Pass `trace.getTracer('my-app')` from
+ * the OpenTelemetry JS API 1.x; it is assignable without a cast.
+ *
+ * Satisfied by the client you pass in. In 1.x, members are only added as optional, and the
+ * library checks that they exist before calling them.
+ */
+interface TracerLike {
+    /**
+     * Starts a span, makes it the active one while `fn` runs (so spans started inside `fn` are
+     * its children), and returns what `fn` returns. Must call `fn` synchronously.
+     */
+    startActiveSpan<F extends (span: SpanLike) => unknown>(name: string, options: SpanOptionsLike, fn: F): ReturnType<F>;
+    /** Starts a span under the active one without activating it (the `cache.lock` wait). */
+    startSpan(name: string, options?: SpanOptionsLike): SpanLike;
+}
+/** Options of `CacheTracingModule.forRoot`. */
+interface CacheTracingOptions {
+    /** The tracer spans are started with, for example `trace.getTracer('my-app')`. */
+    tracer: TracerLike;
+    /**
+     * Record `cache.key`: the full key (prefix and namespace version included), an array of full
+     * keys on batch calls and `delete`, the tag names on `invalidateTags`. Default `false`: keys
+     * may hold user data and have a very large number of values.
+     */
+    recordKeys?: boolean;
+}
+/** Options of `CacheTracingModule.forRootAsync`: `useFactory` resolves the module options. */
+interface CacheTracingAsyncOptions {
+    imports?: ModuleMetadata['imports'];
+    /** Providers passed to `useFactory`, in order. */
+    inject?: FactoryProvider['inject'];
+    /** Returns the module options, or a promise of them. */
+    useFactory: (...args: never[]) => CacheTracingOptions | Promise<CacheTracingOptions>;
+}
+
+/** The store (and namespace) a main or refresh span is about. */
+interface TraceBase {
+    store: string;
+    namespace?: string;
+}
+/**
+ * Internal: not part of the public API. Owns the user's tracer once `CacheTracingModule`
+ * registers it, and the current cache scope (an `AsyncLocalStorage`, created on registration).
+ * Until then every method calls its function directly or does nothing. A throwing tracer or span
+ * method is logged (as `'tracing'`) and never reaches the caller, and never runs a function twice.
+ */
+declare class CacheTracing {
+    private readonly logger?;
+    private on;
+    /** Whether a tracer is registered. */
+    get enabled(): boolean;
+    /** Whether `cache.key` is recorded; lets a caller skip building a key list for `key`. */
+    get recordKeys(): boolean;
+    /** Registers the tracer; throws `CacheConfigError` for invalid options or a second call. */
+    use(options: CacheTracingOptions): void;
+    /**
+     * Runs `fn` in a new active main span `name` and its own scope. A rejection (or a
+     * synchronous throw) records the exception and sets `ERROR`, then reaches the caller as is.
+     * A `'batch'` scope counts hits, stale hits and misses instead of setting `cache.result`, and
+     * its span always gets the three counters, 0 when none.
+     */
+    span<T>(name: string, base: TraceBase, fn: () => Promise<T>, kind?: 'single' | 'batch'): Promise<T>;
+    /**
+     * Runs `fn` in an active child span of the current one. A rejection marks the child and the
+     * current scope's span `ERROR`. Untraced outside a scope or after the scope ended.
+     */
+    child<T>(name: 'cache.load', fn: () => Promise<T>): Promise<T>;
+    /**
+     * Runs `fn` in a new root span `cache.refresh` linked to the current scope's span (no link
+     * outside a scope), in a scope of its own: a background refresh outlives its trigger. If the
+     * tracer fails, `fn` runs untraced outside any scope, so it never writes to its trigger.
+     */
+    root<T>(base: TraceBase, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Starts `cache.lock` under the active span, not activated. `end` is idempotent; `true` or
+     * `false` sets `cache.lock.acquired`, `undefined` (the acquire failed) sets nothing.
+     */
+    lockSpan(): {
+        end(acquired: boolean | undefined): void;
+    };
+    /** A hit: `cache.result` `'hit'`/`'stale'` on a single scope, a count on a batch scope. */
+    hit(stale: boolean): void;
+    /** A miss: `cache.result = 'miss'` on a single scope, a count on a batch scope. */
+    miss(): void;
+    /** Sets `cache.result` (`'bypass'`: the call skipped the cache). */
+    result(value: 'bypass'): void;
+    /** Sets one attribute on the current scope's span. */
+    set(key: string, value: SpanAttributeValue): void;
+    /** Sets `cache.key` (a full key, or a list of them) when `recordKeys` is on. */
+    key(full: string | readonly string[]): void;
+    /**
+     * A failure the library swallowed: records the exception (unless the span already has it) and
+     * a `cache.error` event carrying `cache.error.operation`. The status stays unset, since the
+     * caller still gets a result.
+     */
+    error(operation: CacheOperation, error: unknown): void;
+    /** The live scope, or `undefined` when tracing is off, outside a scope, or after it ended. */
+    private current;
+    /** Starts an active span that owns a new scope (`span`, `root`). */
+    private scoped;
+    /**
+     * Calls `tracer.startActiveSpan` with `body`. If the tracer throws before calling `body`, or
+     * returns without calling it, `untraced` runs instead; if it throws after, the outcome of
+     * `body` is kept. Either way the user function runs once: a callback the tracer invokes again,
+     * or late (after the fallback ran), only ends its span. A synchronous throw of the user
+     * function is rethrown here, not mistaken for a tracer error.
+     */
+    private activate;
+    /**
+     * Runs `run` and ends `span` once when it settles, on a side branch: the caller gets the
+     * promise `run` returned, so tracing adds no tick, and the side branch's reactions (registered
+     * first) end the span before the caller resumes. The side branch handles the rejection, which
+     * still reaches the caller through the original promise. A rejection or synchronous throw
+     * first calls `onError`, which records it. With a `scope`, the scope is closed (its batch
+     * counters set) before the span ends.
+     */
+    private settle;
+    /**
+     * Marks the scope's span `ERROR` for an error that reaches its caller (a failed child, or the
+     * call's own rejection). An error the span already has (from the child, or a swallowed one) is
+     * not recorded again.
+     */
+    private failScope;
+    /** Records `error` on the scope's span, once per error. */
+    private record;
+    private fail;
+    /** Sets the batch counters and closes the scope; the caller ends the span. */
+    private close;
+    private attribute;
+    /** Runs one tracer or span call; a throw is logged and never escapes. */
+    private guard;
+    private report;
+}
+
+/** What a token versions: a versioned namespace or a cache tag. */
+type TokenKind = 'ns' | 'tag';
+/**
+ * Version tokens per (store, kind, name), for versioned namespaces (`'ns'`) and cache tags
+ * (`'tag'`). Emits nothing; store failures reject. A token key is read with `getStrict` and
+ * written with `setStrict` when the store has them (a tiered store), so a token is never created
+ * or changed in L1 alone while L2 is down. An empty token key counts as missing.
+ */
+declare class VersionTokens {
+    private readonly prefix;
+    private readonly cacheTtl;
+    private readonly kinds;
+    /** `maxTagTokens` is `MAX_TAG_TOKENS` outside tests. */
+    constructor(prefix: string | undefined, cacheTtl: number, maxTagTokens?: number);
+    /** The bump counts `fresh` reads in flight compare, keyed by `<store>\0<name>`. */
+    bumpCounts(kind: TokenKind): ReadonlyMap<string, number>;
+    /**
+     * The token of `name`: cached for `cacheTtl`, else read from the store, and created when the
+     * key is missing. Concurrent reads of one name share one store read.
+     */
+    current(target: Target, kind: TokenKind, name: string): Promise<string>;
+    /** The token this instance has cached, even past `cacheTtl`; never reads the store. */
+    cached(target: Target, kind: TokenKind, name: string): string | undefined;
+    /**
+     * Reads the token from the store (creating it when missing), bypassing the cache, then caches
+     * it for `cacheTtl`. A bump that completes during the read keeps its token in the cache.
+     */
+    fresh(target: Target, kind: TokenKind, name: string): Promise<string>;
+    /**
+     * Whether `name` may be re-read now (spec 3.3 step 3): true at most once per `cacheTtl` per
+     * (store, name), and the time is recorded. The record keeps at most as many slots as the
+     * token cache (`MAX_TAG_TOKENS` for tags), evicting the oldest first.
+     */
+    mayRecheck(target: Target, kind: TokenKind, name: string): boolean;
+    /**
+     * Re-reads the token of `name` from the store, bypassing the cache, for a stamp that differs
+     * from the cached token (spec 3.3). Joins the slot's re-read in flight; otherwise starts one
+     * when `mayRecheck` allows it, and returns `undefined` (no read) when it does not. Never
+     * creates the token: a missing or empty key resolves `undefined` and drops a cached tag
+     * token. As with `fresh`, the result is cached unless a bump completed meanwhile; a bump also
+     * unregisters the re-read, so no later call joins a read older than the bump. A rejection
+     * reaches every waiter and caches nothing.
+     */
+    recheck(target: Target, kind: TokenKind, name: string): Promise<string | undefined> | undefined;
+    /**
+     * The store's token of `name`, bypassing the cache; `create` writes one when the key is
+     * missing, else a missing (or empty) key is `undefined`. What it read is cached unless a bump
+     * completed during the read; a missing tag key then drops the cached token instead.
+     */
+    private readFresh;
+    /** Writes a new token and caches it; on a failed write the cached token is unchanged. */
+    bump(target: Target, kind: TokenKind, name: string): Promise<void>;
+    /**
+     * The tokens of `names` (deduplicated, in first-occurrence order), `undefined` for a missing
+     * or empty key; never creates one. Cached tokens are served without a store call. A name with
+     * a plain read already in flight (from another `currentMany`) joins it; the others are read
+     * with one `getStrict` each, in parallel, when the store has it, else with one `getMany` (one
+     * `get` each without it). A token read is cached unless a bump or a fresh read completed
+     * meanwhile, and an older read-or-create still in flight then no longer updates the cache; a
+     * missing key is not cached, and for a tag it also drops the cached token. A `current` that
+     * caches a token also unregisters a plain read still in flight, so that read cannot undo it.
+     * Rejects when any store read rejects, for every waiter on it. The names served from the
+     * process cache (not read by this call nor joined to a read) are added to `fromCache`.
+     */
+    currentMany(target: Target, kind: TokenKind, names: readonly string[], fromCache?: Set<string>): Promise<Map<string, string | undefined>>;
+    /**
+     * `current` for each of `names` (deduplicated), in parallel: missing tokens are created, and
+     * reads already in flight are shared. Rejects when any read or create rejects.
+     */
+    ensureMany(target: Target, kind: TokenKind, names: readonly string[]): Promise<Map<string, string>>;
+    /**
+     * `bump` for each of `names` (deduplicated), in parallel. Every name is tried; then the call
+     * rejects with the first failing name's error. Successful bumps are cached either way.
+     */
+    bumpMany(target: Target, kind: TokenKind, names: readonly string[]): Promise<void>;
+    /**
+     * Registers the plain read of `k` so concurrent `currentMany` calls join it. On success a token
+     * is cached while the read is still registered; `''` becomes `undefined`. A rejection is
+     * passed to every waiter and caches nothing.
+     */
+    private shareRead;
+    /** Caches `token` as the most recently refreshed entry, evicting the oldest beyond the cap. */
+    private remember;
+    /** Reads the token key, creating it when missing; a concurrent creator's token wins. */
+    private read;
+}
+
+interface Target {
+    name: string;
+    store: CacheStore;
+}
+
+/** The tag versions an entry was written with: each tag mapped to its token. */
+type TagStamp = Readonly<Record<string, string>>;
+/**
+ * The engine-level tags of a single write (D2). An array is known before the load, so its tokens
+ * are taken before the loader runs; a function gets the value once the write is decided.
+ */
+type TagOption<T> = readonly string[] | ((value: T) => readonly string[]);
+/** The tags of a batch write (D2): an array for every entry, or a function of each entry. */
+type BatchTagOption<T> = readonly string[] | ((value: T, key: string) => readonly string[]);
+/**
+ * How a write is stamped: a stamp (empty means the untagged 0.6 envelope), or `'skip'` after a
+ * reported failure, and the entry is then not written.
+ */
+type Stamping = TagStamp | 'skip';
+
+type Classification = 'fresh' | 'stale' | 'expired';
+interface ExpiryStrategy {
+    readonly kind: 'fixed' | 'swr' | 'sliding';
+    /** The engine adds jitter to the ttl before calling `wrap` when true. */
+    readonly jittered: boolean;
+    /** Only receives non-null/undefined-or-nil values; `ttl` is an integer >= 1. */
+    wrap(value: unknown, now: number, ttl: number): {
+        envelope: CacheEnvelope;
+        storeTtl: number;
+    };
+    read(ttl: number): {
+        touch: false;
+    } | {
+        touch: true;
+        touchTtl: number;
+    };
+    classify(envelope: CacheEnvelope, now: number): Classification;
+}
+
+/** The write policy a loaded or put value is checked against (`writePlan`). */
+interface WritePolicy<T> {
+    ttl?: number;
+    cacheNull?: boolean;
+    nullTtl?: number;
+    unless?: (result: T) => boolean;
+}
+/** `tags` per D2: an array is known before the load, a function gets the value. */
+type PutOptions<T> = WritePolicy<T> & {
+    tags?: TagOption<T>;
+} & LoadStrategyOptions;
+/** `PutOptions` of a batch load: a tag function also gets each entry's key (D2). */
+type BatchPutOptions<T> = WritePolicy<T> & {
+    tags?: BatchTagOption<T>;
+} & LoadStrategyOptions;
+
+interface KeyRef {
+    store?: string;
+    namespace?: string;
+    key: string;
+}
+
+/** The store and namespace a batch call works in. */
+interface BatchScope {
+    store?: string;
+    namespace?: string;
+}
+type BatchLoader<T> = (missing: string[]) => Promise<ReadonlyMap<string, T>>;
+
+/** `lock` overrides `defaults.lock.enabled`; it has no effect on a store without `lock`. */
+type LoadOptions<T> = PutOptions<T> & {
+    lock?: boolean;
+};
+/** `getOrSetMany` options: batch tags (D2); `lock: true` is rejected. */
+type BatchLoadOptions<T> = BatchPutOptions<T> & {
+    lock?: boolean;
+};
+type SetOptions<T = unknown> = {
+    ttl?: number;
+    tags?: TagOption<T>;
+} & LoadStrategyOptions;
+/** `setMany` options: a tag function also gets each entry's key (D2). */
+type BatchSetOptions<T = unknown> = {
+    ttl?: number;
+    tags?: BatchTagOption<T>;
+} & LoadStrategyOptions;
+/** Public facade: validates each call, then delegates to the store I/O and load orchestration. */
+declare class CacheEngine {
+    private readonly options;
+    private readonly tracing;
+    private readonly io;
+    private readonly load;
+    private readonly batch;
+    /** The module's `logging.level`. */
+    readonly logLevel: CacheLogLevel;
+    /** The module's `escapeKeyArgs`; decorators pass it to template key rendering at call time. */
+    readonly escapeKeyArgs: boolean;
+    /** Internal: the version tokens of namespaces and tags, one set per engine. */
+    readonly tokens: VersionTokens;
+    /**
+     * @param tracing Internal: the module's tracing; until a tracer is registered with it, every
+     * call runs untraced, as before 0.10.
+     */
+    constructor(options: ResolvedCacheOptions, events: CacheEvents, tracing?: CacheTracing);
+    hasStore(name: string): boolean;
+    /** True when the store is configured and can lock; never throws for an unknown name. */
+    hasLock(name: string): boolean;
+    storeNames(): string[];
+    /** Never refreshes; `options` selects the read command and the classification only. */
+    get<T>(ref: KeyRef, options?: LoadStrategyOptions): Promise<T | undefined>;
+    private getImpl;
+    /**
+     * @param preset Internal: the strategy built from `options` at decoration time, so a
+     * decorated call does not rebuild it. It must come from `createStrategy(options)`.
+     */
+    getOrSet<T>(ref: KeyRef, loader: () => Promise<T>, options?: LoadOptions<T>, preset?: ExpiryStrategy): Promise<T>;
+    private getOrSetImpl;
+    /** With `tags`, the entry is stamped with their tokens; an invalid list skips the write. */
+    set<T>(ref: KeyRef, value: T, options?: SetOptions<T>): Promise<void>;
+    private setImpl;
+    /**
+     * @param preset Internal: as for `getOrSet`.
+     * @param taken Internal: the stamp `takeTags` gave before the value was produced (T4-B); the
+     * write uses exactly those tokens and `options.tags` is not stamped again.
+     */
+    put<T>(ref: KeyRef, value: T, options?: PutOptions<T>, preset?: ExpiryStrategy, taken?: Stamping): Promise<void>;
+    private putImpl;
+    /**
+     * Internal: takes the tokens of tags known before a value is produced (spec 3.3), for a later
+     * `put`, so an invalidation in between leaves that write stale. An invalid list is one `tag`
+     * error, a failed token write one `version` error; either gives `'skip'` and never rejects.
+     */
+    takeTags(storeName: string | undefined, tags: readonly string[]): Promise<Stamping>;
+    /**
+     * `get` for several keys of one namespace: one store read for the batch (per key under
+     * `sliding`), results in input order. A duplicate is read once; an empty or reserved key is
+     * `undefined`.
+     */
+    getMany<T>(scope: BatchScope, keys: readonly string[], options?: LoadStrategyOptions): Promise<(T | undefined)[]>;
+    private getManyImpl;
+    /**
+     * `set` for several entries, written with one store call. A repeated key is written once,
+     * with its last value; empty or reserved keys are dropped and reported once as a key error.
+     */
+    setMany<T>(scope: BatchScope, entries: readonly (readonly [key: string, value: NoInfer<T>])[], options?: BatchSetOptions<T>): Promise<void>;
+    private setManyImpl;
+    /**
+     * `getOrSet` for several keys of one namespace. Hits (stale `swr` ones too) are served; the
+     * misses go to one `loader(missing)` call, except those another call is loading, which are
+     * awaited. A key the loader omits counts as `undefined`; keys it was not asked for are
+     * ignored. Stale `swr` keys are refreshed in the background with one more loader call.
+     * Results are in input order, duplicates included; an empty or reserved key is
+     * `undefined`. Never locks.
+     */
+    getOrSetMany<T>(scope: BatchScope, keys: readonly string[], loader: BatchLoader<T>, options?: BatchLoadOptions<T>): Promise<(T | undefined)[]>;
+    private getOrSetManyImpl;
+    /** Empty keys are dropped and reported once as a key error; every other key is deleted. */
+    delete(scope: {
+        store?: string;
+        namespace?: string;
+    }, keys: readonly string[]): Promise<void>;
+    private deleteImpl;
+    clear(namespace: string, storeName?: string): Promise<void>;
+    private clearImpl;
+    /**
+     * Gives each tag a new version in the store (spec 3.4), so every entry stamped with one of them
+     * becomes a miss; this instance sees it at once, others once their cached token expires. Rejects
+     * `CacheConfigError` for an invalid list (empty, an empty or non-string tag, more than 32 after
+     * de-duplication) or an unknown store. A failed token write is one `version` error, and the
+     * call rejects with the first failing tag's error once every tag was tried.
+     */
+    invalidateTags(tags: readonly string[], storeName?: string): Promise<void>;
+    private invalidateTagsImpl;
+    reportError(store: string | undefined, operation: CacheOperation, error: unknown): void;
+    /** Names starting with `__` are reserved for internal keys (the lock keys). */
+    private checkNamespace;
+    /** A `getOrSet` that skips the cache: `cache.result = 'bypass'`, the loader in `cache.load`. */
+    private bypass;
+    /** Reports an empty or reserved key as a key error; the caller then skips the cache. */
+    private invalidKey;
+}
+
+/** What a `key` callback receives about the request. */
+interface HttpCacheRequest {
+    method: string;
+    /** The raw request URL, as received (query unsorted, nothing escaped). */
+    url: string;
+    /**
+     * The key used when `key` is not set: the path plus the query sorted by name then value, with
+     * `%` and `:` percent-encoded. It varies on path and query only.
+     */
+    defaultKey: string;
+    path: string;
+    query: Readonly<Record<string, string | readonly string[]>>;
+    params: Readonly<Record<string, string>>;
+    headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+}
+/** Options of `@HttpCache`; the strategy options include `softTimeout` (a cached route loads). */
+type HttpCacheOptions = LoadStrategyOptions & {
+    ttl?: number;
+    /** Defaults to 'http'. */
+    namespace?: string;
+    store?: string;
+    lock?: boolean;
+    cacheNull?: boolean;
+    nullTtl?: number;
+    /**
+     * A string is a fixed key, not a template: a non-empty string without `{` or `}`, and only on a
+     * method (a class-level string throws `CacheConfigError` at decoration). A callback derives the
+     * key per request; `undefined` skips caching that request.
+     */
+    key?: string | ((req: HttpCacheRequest) => string | undefined);
+    /** Returns `true` to keep the body out of the cache. */
+    unless?: (body: unknown) => boolean;
+    /**
+     * Tags the cached body (spec 2.1): fixed strings (not templates), or a callback of the body
+     * and the request, called once the body is to be written.
+     */
+    tags?: readonly string[] | HttpCacheTags;
+};
+/** An `@HttpCache` tags callback. */
+type HttpCacheTags = (body: unknown, req: HttpCacheRequest) => readonly string[];
+/** Caches the HTTP response body of a route (method) or of every route of a controller (class). */
+declare function HttpCache(options?: HttpCacheOptions): MethodDecorator & ClassDecorator;
+
+/**
+ * Caches GET/HEAD response bodies of routes marked with `@HttpCache`; other requests pass through.
+ *
+ * Created by Nest; inject it, do not construct it. Constructor parameters are not part of the
+ * public API.
+ */
+declare class HttpCacheInterceptor implements NestInterceptor {
+    private readonly engine;
+    private readonly reflector;
+    private readonly adapterHost;
+    constructor(engine: CacheEngine, reflector: Reflector, adapterHost: HttpAdapterHost);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+    /** The cache key per spec 3.2; `undefined` skips the cache, a throw is a key error. */
+    private keyOf;
+}
+
+/** Options of `compressedSerializer`. */
+interface CompressedSerializerOptions {
+    /** Produces and reads the string that gets compressed. Default `jsonSerializer`. */
+    inner?: Serializer;
+    /** Algorithm used for writes; reads follow the prefix of the stored value. Default `'gzip'`. */
+    algorithm?: 'gzip' | 'brotli';
+    /**
+     * Compression level: 0-9 for gzip (default 6, zlib's default) and 0-11 for brotli (default 4).
+     * Compression runs synchronously on the event loop. Brotli's own default, 11, is much slower:
+     * about 1.6 s for a 724 KB JSON value, against about 2 ms at 4. Reads accept any level.
+     */
+    level?: number;
+    /** UTF-8 byte length of the inner string above which compression is tried. Default 1024. */
+    threshold?: number;
+    /**
+     * Upper bound of a decompressed payload, in bytes. Default 16 MiB. Larger payloads are written
+     * uncompressed so they stay readable.
+     */
+    maxDecompressedBytes?: number;
+}
+/**
+ * Wraps a serializer with gzip or brotli compression of large payloads. A compressed value is
+ * `"\u0000nc1:gz:"` or `"\u0000nc1:br:"` plus base64; anything else is read by `inner`.
+ * `inner` must not produce strings starting with `"\u0000nc1:"`.
+ */
+declare function compressedSerializer(options?: CompressedSerializerOptions): Serializer;
+
+/** Options of `memoryStore`. */
+interface MemoryStoreOptions {
+    /** Entries kept before the least recently used one is evicted; an integer >= 1. Default 1 000. */
+    maxEntries?: number;
+}
+/**
+ * In-process LRU store on Map insertion order. Expiry is lazy; no timers.
+ *
+ * The version tokens of namespaces and tags live in a second LRU with the same `maxEntries`, so
+ * data writes never evict them. An evicted token would be re-created with a new value, and every
+ * entry of its namespace or tag would then read as a miss.
+ */
+declare class MemoryStore implements CacheStore {
+    private readonly data;
+    private readonly tokens;
+    private reservedPrefixes;
+    constructor(options?: MemoryStoreOptions);
+    /** The data entries in LRU order, oldest first. */
+    private get entries();
+    private partitionOf;
+    ping(): Promise<void>;
+    get(key: string): Promise<string | undefined>;
+    /** Reads the entry and resets its TTL to `ttlMs`; a live hit also becomes most recently used. */
+    getAndTouch(key: string, ttlMs: number): Promise<string | undefined>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    getMany(keys: readonly string[]): Promise<(string | undefined)[]>;
+    /** Writes every entry in one synchronous step, so no other task can interleave between them. */
+    setMany(entries: readonly {
+        key: string;
+        value: string;
+        ttlMs: number;
+    }[]): Promise<void>;
+    delete(keys: readonly string[]): Promise<void>;
+    clear(prefix: string): Promise<void>;
+}
+/** An in-process LRU store; the default store when `CacheModule` gets no `stores`. */
+declare function memoryStore(options?: MemoryStoreOptions): MemoryStore;
+
+/** Terminus-compatible result for one indicator key. */
+type CacheHealthResult = {
+    status: 'up';
+    ping?: 'unsupported';
+} | {
+    status: 'down';
+    message: string;
+};
+/**
+ * Probes a configured store with `ping()` and returns a result in the shape `@nestjs/terminus`
+ * expects, without importing it. `check` never rejects except with `CacheConfigError` for an
+ * unknown store or an invalid timeout; a failing store is reported as `down`.
+ */
+declare class CacheHealthIndicator {
+    private readonly options;
+    /** Created by `CacheModule`; do not construct it, inject it. */
+    constructor(options: ResolvedCacheOptions);
+    check<K extends string>(key: K, options?: {
+        store?: string;
+        timeout?: number;
+    }): Promise<Record<K, CacheHealthResult>>;
+}
+
+/**
+ * The cache module: provides `CacheService`, `CacheEvents` and `CacheHealthIndicator`, and
+ * wires the cache decorators of every provider. Register it once, usually with `isGlobal`.
+ */
+declare class CacheModule {
+    /** Registers the module with options known up front. Invalid options throw `CacheConfigError`. */
+    static forRoot(options?: CacheModuleOptions & {
+        isGlobal?: boolean;
+    }): DynamicModule;
+    /** Registers the module with options built by `useFactory`, which can inject providers. */
+    static forRootAsync(options: CacheModuleAsyncOptions): DynamicModule;
+}
+
+/** Where a key lives: its `namespace` (default none) and `store` name (default `'default'`). */
+interface KeyOptions {
+    namespace?: string;
+    store?: string;
+}
+/**
+ * `tags`: fixed tag strings (not templates), or a function of the value. The entry is stamped
+ * with each tag's version, so `invalidateTags` turns it into a miss. On `getOrSet` an array's
+ * versions are taken before the loader runs; a function runs after it, and only when the entry
+ * is written, so an invalidation during that load can be missed until the entry expires. An
+ * invalid list (an empty tag, more than 32 tags, a throwing function) is an `error` event with
+ * operation `'tag'`: the entry is not written and the call still resolves.
+ */
+type WriteOptions<T = unknown> = KeyOptions & Writes<T> & StrategyOptions;
+/** The options of the batch writes: a tag function also gets each entry's key. */
+type WriteManyOptions<T = unknown> = KeyOptions & WritesMany<T> & StrategyOptions;
+/** `ttl` and `tags` of a single-key write; see `WriteOptions`. */
+interface Writes<T> {
+    ttl?: number;
+    tags?: readonly string[] | ((value: T) => readonly string[]);
+}
+/** `ttl` and `tags` of a batch write; see `WriteManyOptions`. */
+interface WritesMany<T> {
+    ttl?: number;
+    tags?: readonly string[] | ((value: T, key: string) => readonly string[]);
+}
+/** The load options; `L` narrows `lock` (`false` for `getOrSetMany`, which never locks). */
+interface LoadPolicy<T, L extends boolean = boolean> {
+    cacheNull?: boolean;
+    nullTtl?: number;
+    unless?: (result: T) => boolean;
+    lock?: L;
+}
+/**
+ * `getOrSet` options: the `WriteOptions` fields with `LoadStrategyOptions` (so `softTimeout` is
+ * accepted), plus the load policy. It is not built on `WriteOptions`, whose
+ * `softTimeout?: never` would make the intersection reject `softTimeout`.
+ */
+type GetOrSetOptions<T> = KeyOptions & Writes<T> & LoadStrategyOptions & LoadPolicy<T>;
+/**
+ * `getOrSetMany` options. `lock` accepts only `false`: a batch never locks, and `lock: true`
+ * from JavaScript rejects with `CacheConfigError`.
+ */
+type GetOrSetManyOptions<T> = KeyOptions & WritesMany<T> & LoadStrategyOptions & LoadPolicy<T, false>;
+/**
+ * The programmatic cache API, injected from `CacheModule`. Cache failures (store, serializer,
+ * key, lock) are reported as `error` events and do not reject a call, with one exception:
+ * `invalidateTags` rejects with the store's error when a tag version write fails, so the caller
+ * knows the invalidation did not happen. Invalid arguments reject with `CacheConfigError`.
+ */
+declare class CacheService {
+    private readonly engine;
+    /** Created by `CacheModule`; do not construct it, inject it. */
+    constructor(engine: CacheEngine);
+    /**
+     * Reads a value; returns `undefined` on a miss.
+     *
+     * Strategy options pick the read command (`sliding` touches the entry) and how the entry is
+     * classified; a stale `swr` entry is returned as a hit with `stale: true`. `get` never refreshes.
+     *
+     * With `strategy: 'sliding'` the entry's window is reset to `defaults.ttl`, not to the `ttl` it
+     * was written with, because `getAndTouch` needs the TTL before the entry is read.
+     */
+    get<T>(key: string, options?: KeyOptions & StrategyOptions): Promise<T | undefined>;
+    /**
+     * Writes a value with `options.ttl` (else `defaults.ttl`). An empty value (`null` or
+     * `undefined`) is written as is, under the `fixed` strategy.
+     */
+    set<T>(key: string, value: T, options?: WriteOptions<T>): Promise<void>;
+    /** Deletes one key or several keys of one namespace and store, with one store call. */
+    delete(key: string | readonly string[], options?: KeyOptions): Promise<void>;
+    /**
+     * Deletes every entry of `namespace` in the store (`options.store`, else `default`): the
+     * store's `clear` of its key prefix, or one version token change for a versioned namespace.
+     * Rejects `CacheConfigError` for `''`.
+     */
+    clear(namespace: string, options?: {
+        store?: string;
+    }): Promise<void>;
+    /**
+     * Returns the cached value, or runs `loader` once per key across concurrent callers (and, with
+     * `lock`, across instances), stores its result and returns it. A loader error rejects the
+     * call; nothing is stored. Under `swr` a stale value is served while one refresh runs.
+     */
+    getOrSet<T>(key: string, loader: () => Promise<T>, options?: GetOrSetOptions<T>): Promise<T>;
+    /**
+     * Invalidates every entry stamped with one of `tags` in the store (`options.store`, else
+     * `default`), across namespaces: each tag gets a new version, so those entries read as misses.
+     * This instance sees it at once; other instances once their cached version expires
+     * (`versioning.cacheTtl`). Tags are plain strings, used as is.
+     *
+     * Rejects with `CacheConfigError` when `tags` is not a non-empty array of non-empty strings,
+     * has more than 32 tags after de-duplication, or the store is unknown. When a version write
+     * fails, every tag is still tried; an `error` event with operation `'version'` is emitted and
+     * the call rejects with the first failure.
+     */
+    invalidateTags(tags: readonly string[], options?: {
+        store?: string;
+    }): Promise<void>;
+    /**
+     * Reads several keys of one namespace and store; results follow `keys`, `undefined` for a
+     * miss. One store read for the batch (MGET on Redis), except with `strategy: 'sliding'`,
+     * which touches each entry with its own `getAndTouch`.
+     */
+    getMany<T>(keys: readonly string[], options?: KeyOptions & StrategyOptions): Promise<(T | undefined)[]>;
+    /** Writes several entries, each as `set` would, with one store call when the store allows. */
+    setMany<T>(entries: readonly (readonly [key: string, value: T])[], options?: WriteManyOptions<T>): Promise<void>;
+    /**
+     * `getOrSet` for several keys: hits are served, and the misses are loaded with one
+     * `loader(missing)` call that resolves a Map. A key the loader omits is treated as
+     * `undefined`; keys it was not asked for are ignored. `lock: true` is not supported.
+     */
+    getOrSetMany<T>(keys: readonly string[], loader: (missing: string[]) => Promise<ReadonlyMap<string, T>>, options?: GetOrSetManyOptions<T>): Promise<(T | undefined)[]>;
+}
+
+/**
+ * Minimal Redis surface the cache needs; implemented over ioredis by `ioredisAdapter` and over
+ * node-redis by `nodeRedisAdapter`.
+ *
+ * Implemented by you. In 1.x, members are only added as optional, and the library checks that
+ * they exist before calling them.
+ *
+ * `redisStore` tells an adapter from an ioredis client by checking that `createSubscriber` is a
+ * function.
+ */
+interface RedisClientAdapter {
+    get(key: string): Promise<string | undefined>;
+    /** SET key value PX ttlMs */
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    /** GETEX key PX ttlMs */
+    getex(key: string, ttlMs: number): Promise<string | undefined>;
+    /**
+     * An empty list sends no command. The keys may belong to several hash slots; a Cluster adapter
+     * must split the command per slot.
+     */
+    unlink(keys: readonly string[]): Promise<void>;
+    scan(cursor: string, match: string, count: number): Promise<{
+        cursor: string;
+        keys: string[];
+    }>;
+    /**
+     * Optional. SET key value PX ttlMs NX. Resolves `true` when the key was set, `false` when it
+     * already existed.
+     */
+    setIfAbsent?(key: string, value: string, ttlMs: number): Promise<boolean>;
+    /**
+     * Optional. Deletes `key` only if it holds `value`, atomically. Resolves `true` when it
+     * deleted the key.
+     */
+    deleteIfEquals?(key: string, value: string): Promise<boolean>;
+    /** Optional. Sends a PING; resolves when Redis answers, rejects otherwise. */
+    ping?(): Promise<void>;
+    /**
+     * Optional. MGET; resolves the values in key order, `undefined` for a missing key. An empty
+     * list sends no command and resolves `[]`. The keys may belong to several hash slots; a
+     * Cluster adapter must split the command per slot.
+     */
+    mget?(keys: readonly string[]): Promise<(string | undefined)[]>;
+    /**
+     * Optional. Every key matching `match`, in pages, across every node that holds data (each master
+     * of a cluster). When present, `RedisStore.clear` uses it instead of the `scan` cursor loop.
+     */
+    scanIterator?(match: string, count: number): AsyncIterable<string[]>;
+    publish(channel: string, message: string): Promise<void>;
+    createSubscriber(): RedisSubscriberAdapter;
+}
+/**
+ * The subscriber connection of a `RedisClientAdapter`, used by the invalidation bus.
+ *
+ * Implemented by you. In 1.x, members are only added as optional, and the library checks that
+ * they exist before calling them.
+ */
+interface RedisSubscriberAdapter {
+    /**
+     * Subscribes to `channel`. If it rejects (for example Redis was unreachable), the adapter
+     * should subscribe again once the connection is ready, and a later call retries too.
+     */
+    subscribe(channel: string, onMessage: (message: string) => void): Promise<void>;
+    /**
+     * Fires on every 'ready' after the first (the first is the initial connect), and when a
+     * subscription that had failed is established later: messages may have been missed meanwhile.
+     */
+    onReconnect(handler: () => void): void;
+    /**
+     * Optional. Registers a handler for errors of the dedicated connection (connection errors,
+     * failed re-subscribes). Handlers must not throw.
+     */
+    onError?(handler: (error: unknown) => void): void;
+    /** Quits the dedicated connection; calling it again is a no-op. Never rejects. */
+    close(): Promise<void>;
+}
+
+/**
+ * Structural subset of an ioredis client (v5 and v6). Declared by hand so the
+ * library never imports ioredis.
+ *
+ * Satisfied by the client you pass in. In 1.x, members are only added as optional, and the
+ * library checks that they exist before calling them.
+ */
+interface IoredisLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, mode: 'PX', ttlMs: number): Promise<unknown>;
+    set(key: string, value: string, mode: 'PX', ttlMs: number, nx: 'NX'): Promise<'OK' | null>;
+    eval(script: string, numKeys: number, ...args: string[]): Promise<unknown>;
+    getex(key: string, mode: 'PX', ttlMs: number): Promise<string | null>;
+    unlink(...keys: string[]): Promise<unknown>;
+    scan(cursor: string, matchToken: 'MATCH', pattern: string, countToken: 'COUNT', count: number): Promise<[cursor: string, keys: string[]]>;
+    publish(channel: string, message: string): Promise<unknown>;
+    /** Optional. Used by health checks; the adapter exposes `ping` only when it exists. */
+    ping?(): Promise<unknown>;
+    /** Optional. Used by batch reads; the adapter exposes `mget` only when it exists. */
+    mget?(...keys: string[]): Promise<(string | null)[]>;
+    duplicate(): IoredisLike;
+    subscribe(...channels: string[]): Promise<unknown>;
+    on(event: string, listener: (...args: never[]) => void): unknown;
+    quit(): Promise<unknown>;
+    /** Optional. Closes the connection at once; used when `quit` does not settle in time. */
+    disconnect?(): void;
+}
+/** The data commands a Cluster shares with a single-node client. */
+type IoredisCommands = Omit<IoredisLike, 'duplicate' | 'on'>;
+/**
+ * Structural subset of an ioredis `Cluster` (ioredis 5.6.0 or later, for sharded pub/sub).
+ * Declared by hand so the library never imports ioredis. `ioredisAdapter` runs in Cluster mode
+ * when `isCluster` is `true`.
+ *
+ * Satisfied by the client you pass in. In 1.x, members are only added as optional, and the
+ * library checks that they exist before calling them.
+ */
+interface IoredisClusterLike extends IoredisCommands {
+    readonly isCluster: boolean;
+    /** The master nodes; `scanIterator` scans each of them. */
+    nodes(role: 'master'): IoredisLike[];
+    spublish(channel: string, message: string): Promise<unknown>;
+    ssubscribe(...channels: string[]): Promise<unknown>;
+    on(event: string, listener: (...args: any[]) => void): unknown;
+    /** The adapter's subscriber is `duplicate([], { shardedSubscribers: true })`. */
+    duplicate(startupNodes?: unknown[], options?: {
+        shardedSubscribers?: boolean;
+    }): IoredisClusterLike;
+}
+/**
+ * Adapts an ioredis client or Cluster to `RedisClientAdapter`. `redisStore` does this itself;
+ * call it to wrap or decorate the adapter.
+ */
+declare function ioredisAdapter(client: IoredisLike | IoredisClusterLike): RedisClientAdapter;
+
+/** Options of `redisInvalidationBus`. */
+interface RedisInvalidationBusOptions {
+    /** An ioredis client or Cluster, or a `RedisClientAdapter` (e.g. `nodeRedisAdapter(client)`). */
+    client: IoredisLike | IoredisClusterLike | RedisClientAdapter;
+    /** The pub/sub channel of invalidation messages. Defaults to 'nestjs-cache:invalidate'. */
+    channel?: string;
+}
+/**
+ * The Redis pub/sub `InvalidationBus` a `RedisStore` uses, on its own: for a custom store, or a
+ * `tieredStore` whose L2 is not Redis. Its subscriber is created on the first `subscribe`.
+ */
+declare function redisInvalidationBus(options: RedisInvalidationBusOptions): InvalidationBus;
+
+/**
+ * Options of `redisStore`: the client and the invalidation channel, the same fields as
+ * `RedisInvalidationBusOptions`.
+ */
+interface RedisStoreOptions extends RedisInvalidationBusOptions {
+}
+/**
+ * A Redis store over an ioredis client or Cluster, or any `RedisClientAdapter` (node-redis via
+ * `nodeRedisAdapter`). It brings a pub/sub invalidation bus on `channel`, and a lock when the
+ * adapter can `setIfAbsent` and `deleteIfEquals`. The caller's client is never closed.
+ */
+declare class RedisStore implements CacheStore {
+    readonly invalidation: InvalidationBus;
+    /** Present only when the adapter implements `setIfAbsent` and `deleteIfEquals`. */
+    readonly lock?: LockProvider;
+    /** Present only when the adapter implements `ping`. */
+    readonly ping?: () => Promise<void>;
+    private readonly adapter;
+    constructor(options: RedisStoreOptions);
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    getMany(keys: readonly string[]): Promise<(string | undefined)[]>;
+    setMany(entries: readonly {
+        key: string;
+        value: string;
+        ttlMs: number;
+    }[]): Promise<void>;
+    delete(keys: readonly string[]): Promise<void>;
+    clear(prefix: string): Promise<void>;
+    getAndTouch(key: string, ttlMs: number): Promise<string | undefined>;
+    /** Closes the bus's subscriber connection; the caller's client is left open. */
+    close(): Promise<void>;
+}
+/** Builds a `RedisStore`; requires Redis 6.2 or later (`GETEX`). */
+declare function redisStore(options: RedisStoreOptions): RedisStore;
+
+/** node-redis's pub/sub listener: it receives the message first, then the channel. */
+type PubSubListener = (message: string, channel: string) => void;
+/**
+ * Structural subset of a node-redis v5 or v6 client (`createClient()` from `redis`). Declared
+ * by hand so the library never imports `redis`. The client must be connected before it is
+ * passed to `nodeRedisAdapter`; the library never connects it.
+ *
+ * Satisfied by the client you pass in. In 1.x, members are only added as optional, and the
+ * library checks that they exist before calling them.
+ */
+interface NodeRedisLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options: {
+        expiration: {
+            type: 'PX';
+            value: number;
+        };
+        condition?: 'NX';
+    }): Promise<string | null>;
+    getEx(key: string, options: {
+        type: 'PX';
+        value: number;
+    }): Promise<string | null>;
+    eval(script: string, options: {
+        keys: string[];
+        arguments: string[];
+    }): Promise<unknown>;
+    unlink(keys: string[]): Promise<unknown>;
+    mGet(keys: string[]): Promise<(string | null)[]>;
+    /** Optional. Used by health checks; the adapter exposes `ping` only when it exists. */
+    ping?(): Promise<unknown>;
+    scan(cursor: string, options: {
+        MATCH: string;
+        COUNT: number;
+    }): Promise<{
+        cursor: string;
+        keys: string[];
+    }>;
+    publish(channel: string, message: string): Promise<unknown>;
+    /** The subscriber's dedicated connection: a new, unconnected client. */
+    duplicate(): NodeRedisLike;
+    connect(): Promise<unknown>;
+    subscribe(channel: string, listener: PubSubListener): Promise<unknown>;
+    close(): Promise<unknown>;
+    destroy(): void;
+    on(event: string, listener: (...args: any[]) => void): unknown;
+}
+/**
+ * Structural subset of a node-redis v5 or v6 cluster (`createCluster()` from `redis`). Declared
+ * by hand so the library never imports `redis`. `nodeRedisAdapter` runs in cluster mode when the
+ * client has `masters`. Like a single client, it must be connected before it is passed in.
+ *
+ * Satisfied by the client you pass in. In 1.x, members are only added as optional, and the
+ * library checks that they exist before calling them.
+ */
+interface NodeRedisClusterLike extends Omit<NodeRedisLike, 'scan' | 'duplicate'> {
+    /** The master nodes, passed back to `nodeClient`; `scanIterator` scans each of them. */
+    readonly masters: readonly unknown[];
+    /** The client of one master node. */
+    nodeClient(master: unknown): Promise<Pick<NodeRedisLike, 'scan'>>;
+    sPublish(channel: string, message: string): Promise<unknown>;
+    sSubscribe(channel: string, listener: PubSubListener): Promise<unknown>;
+    /** The subscriber's dedicated connection: a new, unconnected cluster. */
+    duplicate(): NodeRedisClusterLike;
+}
+/**
+ * Structural subset of a node-redis v5 or v6 Sentinel client (`createSentinel()` from `redis`).
+ * Declared by hand so the library never imports `redis`. `nodeRedisAdapter` runs in Sentinel
+ * mode when `getSentinelNode` is a function. Data commands go to the sentinel, which sends them
+ * to the current master. It has no `duplicate`: the subscriber subscribes on the sentinel
+ * itself, whose pub/sub connection follows the master, and closing the subscriber only
+ * unsubscribes its own channels; the sentinel is never closed. Like a single client, it must be
+ * connected before it is passed in.
+ *
+ * Satisfied by the client you pass in. In 1.x, members are only added as optional, and the
+ * library checks that they exist before calling them.
+ */
+interface NodeRedisSentinelLike extends Omit<NodeRedisLike, 'duplicate'> {
+    /** Marks a Sentinel client; never called. */
+    getSentinelNode(): unknown;
+    /**
+     * Removes one listener of `channel`; the channel's other listeners keep it subscribed. node-redis
+     * types the listener for string and buffer mode alike.
+     */
+    unsubscribe(channel: string, listener: AnyModePubSubListener): Promise<unknown>;
+    off(event: string, listener: (arg: unknown) => void): unknown;
+}
+/** A pub/sub listener as node-redis types it for either mode: string or buffer messages. */
+type AnyModePubSubListener = (message: string | Uint8Array, channel: string | Uint8Array) => void;
+/**
+ * Adapts a connected node-redis v5 or v6 client, cluster or Sentinel to the cache's
+ * `RedisClientAdapter`. A cluster (spec 3.4) splits `mget`/`unlink` per slot, scans every master
+ * through `scanIterator`, and publishes and subscribes with sharded pub/sub. A Sentinel subscribes
+ * on itself (see `NodeRedisSentinelLike`).
+ */
+declare function nodeRedisAdapter(client: NodeRedisLike | NodeRedisClusterLike | NodeRedisSentinelLike): RedisClientAdapter;
+
+/** Options of `tieredStore`. */
+interface TieredStoreOptions {
+    /** The local tier, usually `memoryStore()`. */
+    l1: CacheStore;
+    /** The shared tier, usually `redisStore(...)`; its bus is used unless `invalidation` is set. */
+    l2: CacheStore;
+    /** Upper bound on how long a value lives in L1. Defaults to 10_000 ms. */
+    l1Ttl?: number;
+    /** Overrides `l2.invalidation`. */
+    invalidation?: InvalidationBus;
+}
+/**
+ * Two-tier store: a fast local L1 in front of a shared L2. Every write, delete and clear is
+ * published on the invalidation bus so other instances drop their L1 copies. Failures are reported
+ * through the sink given to `bind`; no method rejects except `getStrict` and `setStrict`, which
+ * reject when L2 cannot be read or written.
+ */
+declare class TieredStore implements CacheStore {
+    /** The L2's lock, when it has one. */
+    readonly lock?: LockProvider;
+    /** Present only when the L2 has `ping`; probes the L2. */
+    readonly ping?: () => Promise<void>;
+    private readonly l1;
+    private readonly l2;
+    private readonly l1Ttl;
+    private readonly bus;
+    private readonly ownedBus;
+    private readonly origin;
+    private readonly logger;
+    private sink;
+    private subscribed;
+    private warned;
+    private closing;
+    /**
+     * One token per key with an L2 read in flight. Invalidating a key drops its token, so a read
+     * that straddles an invalidation does not backfill L1 with the value it read before it.
+     */
+    private readonly pending;
+    constructor(options: TieredStoreOptions);
+    bind(sink: CacheEventSink): void;
+    get(key: string): Promise<string | undefined>;
+    /**
+     * Like `get`, but an L2 failure (including `CircuitOpenError`) is reported as `get` and then
+     * rejects with that error instead of counting as a miss. An L1 failure still counts as a miss.
+     */
+    getStrict(key: string): Promise<string | undefined>;
+    /**
+     * Reads several keys: L1 first, then one L2 read for the misses, backfilling L1 (with `l1Ttl`)
+     * only the keys not invalidated meanwhile. A failing tier counts as misses; an L2 failure is
+     * reported once for the batch.
+     */
+    getMany(keys: readonly string[]): Promise<(string | undefined)[]>;
+    /**
+     * Writes L2 first, then L1 (each TTL capped at `l1Ttl`), then publishes one message with every
+     * key, unless the L2 refused the write because its circuit is open.
+     */
+    setMany(entries: readonly {
+        key: string;
+        value: string;
+        ttlMs: number;
+    }[]): Promise<void>;
+    /**
+     * Reads the value and resets its TTL to `ttlMs` on L2 (through `l2.getAndTouch` when it has
+     * one, otherwise `l2.get`). L1 is read but never extended; a backfill lives `min(ttlMs, l1Ttl)`.
+     */
+    getAndTouch(key: string, ttlMs: number): Promise<string | undefined>;
+    /** L1 read; a failure is reported as `get` and counts as a miss. */
+    private readL1;
+    /**
+     * L2 read after an L1 miss, backfilling L1 unless the key was invalidated meanwhile. A failure
+     * is reported as `get` and counts as a miss, or, when `strict`, rejects with the same error.
+     */
+    private readL2;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    /**
+     * Like `set`, but an L2 failure (including `CircuitOpenError`) is reported as `set` and then
+     * rejects with that error; L1 is not written and nothing is published. Once L2 stored the
+     * value, it continues as `set` does.
+     */
+    setStrict(key: string, value: string, ttlMs: number): Promise<void>;
+    /** The rest of a set once L2 was tried: L1 with `min(ttlMs, l1Ttl)`, then the publish. */
+    private afterL2Set;
+    delete(keys: readonly string[]): Promise<void>;
+    clear(prefix: string): Promise<void>;
+    /** Idempotent. Closes both tiers and a bus passed in options; `l2.invalidation` belongs to `l2`. */
+    close(): Promise<void>;
+    private closeAll;
+    private readonly onMessage;
+    private readonly onReconnect;
+    /** Errors the bus handles internally, such as a lost subscriber connection. */
+    private readonly onBusError;
+    /** Drops the pending read token of `key` if it is still `token`; true when it was. */
+    private release;
+    private forgetKeys;
+    private forgetPrefix;
+    private publish;
+    /**
+     * Runs `fn`, reporting a rejection or a synchronous throw. Never rejects. Returns the caught
+     * error, or `undefined` on success.
+     */
+    private attempt;
+    private report;
+}
+/** Builds a two-tier store (see `TieredStore`). */
+declare function tieredStore(options: TieredStoreOptions): TieredStore;
+
+/** Options of `circuitBreakerStore`. */
+interface CircuitBreakerStoreOptions {
+    /** Consecutive failures that open the circuit. Integer >= 1; defaults to 5. */
+    failureThreshold?: number;
+    /** How long the circuit stays open before a probe is allowed, in ms. Defaults to 10_000. */
+    openDuration?: number;
+    /**
+     * Per-operation timeout in ms; a timeout counts as a failure. Does not apply to `clear`.
+     * Defaults to 500.
+     */
+    timeout?: number;
+}
+/** Rejection of an operation that the circuit breaker did not pass to the store. */
+declare class CircuitOpenError extends Error {
+    constructor(message?: string);
+    /**
+     * The ESM and CommonJS builds each define this class, so `instanceof` also accepts any `Error`
+     * named `CircuitOpenError`. Subclasses keep the normal prototype check.
+     */
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+/**
+ * Wraps a store with a circuit breaker (spec 0.2, 4.6). `get`, `set`, `delete`, `clear`,
+ * `getAndTouch`, `getMany`, `setMany`, `getStrict`, `setStrict`, `ping`, `lock.acquire` and
+ * `LockHandle.release` are guarded: each races a timeout, except `clear`. `clear` runs only
+ * while the circuit is closed (open or half-open it rejects with `CircuitOpenError`, and it is
+ * never the half-open probe); it is not bounded by `timeout`, so set a command or socket timeout
+ * on the client. Its real outcome is recorded once. `failureThreshold` consecutive failures open
+ * the circuit so calls reject with
+ * `CircuitOpenError` without reaching the store. After `openDuration` one probe is let through.
+ * `invalidation`, `bind` and `close` are forwarded unchanged.
+ */
+declare class CircuitBreakerStore implements CacheStore {
+    /** Present only when the inner store has `getAndTouch`. */
+    readonly getAndTouch?: (key: string, ttlMs: number) => Promise<string | undefined>;
+    /** Present only when the inner store has `getMany`; one batch counts as one outcome. */
+    readonly getMany?: (keys: readonly string[]) => Promise<(string | undefined)[]>;
+    /** Present only when the inner store has `setMany`; one batch counts as one outcome. */
+    readonly setMany?: (entries: readonly {
+        key: string;
+        value: string;
+        ttlMs: number;
+    }[]) => Promise<void>;
+    /** Present only when the inner store has `getStrict`. */
+    readonly getStrict?: (key: string) => Promise<string | undefined>;
+    /** Present only when the inner store has `setStrict`. */
+    readonly setStrict?: (key: string, value: string, ttlMs: number) => Promise<void>;
+    /** Present only when the inner store has a lock; `acquire` and `release` are guarded. */
+    readonly lock?: LockProvider;
+    /** Present only when the inner store has `ping`; guarded like every other operation. */
+    readonly ping?: () => Promise<void>;
+    /** The inner store's bus, when it has one. */
+    readonly invalidation?: InvalidationBus;
+    private readonly inner;
+    private readonly failureThreshold;
+    private readonly openDuration;
+    private readonly timeout;
+    private current;
+    private failures;
+    private openedAt;
+    /**
+     * Bumped on every state change. An operation only affects the state if no change happened
+     * since it was admitted, so late outcomes from an earlier state are ignored.
+     */
+    private generation;
+    private sink;
+    constructor(inner: CacheStore, options?: CircuitBreakerStoreOptions);
+    get state(): BreakerState;
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    delete(keys: readonly string[]): Promise<void>;
+    clear(prefix: string): Promise<void>;
+    bind(sink: CacheEventSink): void;
+    close(): Promise<void>;
+    private guardHandle;
+    /**
+     * Admits the call or rejects it with `CircuitOpenError`, then races it against the timeout
+     * (unless `timed` is false, as for `clear`). The first outcome (result, rejection or timeout)
+     * settles the call and is recorded once.
+     */
+    private guard;
+    private record;
+    private open;
+    private reset;
+    private transition;
+}
+/** Wraps `store` with a circuit breaker. Throws `CacheConfigError` for invalid options. */
+declare function circuitBreakerStore(store: CacheStore, options?: CircuitBreakerStoreOptions): CircuitBreakerStore;
+
+/**
+ * Structural subset of a Prometheus registry; satisfied by prom-client and @prometheus-io/client.
+ *
+ * Satisfied by the client you pass in. In 1.x, members are only added as optional, and the
+ * library checks that they exist before calling them.
+ */
+interface RegistryLike {
+    getSingleMetric(name: string): unknown;
+    removeSingleMetric(name: string): void;
+    /** Real clients call this on every entry of `registers` while constructing a metric. */
+    registerMetric(metric: unknown): void;
+}
+type PrometheusConstructor<TInstance> = new (config: never) => TInstance;
+/**
+ * Structural subset of a prom-client-compatible client module; pass
+ * `import * as client from '...'`.
+ *
+ * Satisfied by the client you pass in. In 1.x, members are only added as optional, and the
+ * library checks that they exist before calling them.
+ *
+ * A minimal hand-written fake, for tests:
+ *
+ * ```ts
+ * const registry: RegistryLike = {
+ *   getSingleMetric: () => undefined,
+ *   removeSingleMetric: () => undefined,
+ *   registerMetric: () => undefined,
+ * };
+ * class FakeMetric {
+ *   inc(): void {}
+ *   observe(): void {}
+ *   set(): void {}
+ * }
+ * const client: PrometheusClientLike = {
+ *   Counter: FakeMetric,
+ *   Histogram: FakeMetric,
+ *   Gauge: FakeMetric,
+ *   register: registry,
+ * };
+ * ```
+ */
+interface PrometheusClientLike {
+    Counter: PrometheusConstructor<{
+        inc(labels: Record<string, string>): void;
+    }>;
+    Histogram: PrometheusConstructor<{
+        observe(labels: Record<string, string>, value: number): void;
+    }>;
+    Gauge: PrometheusConstructor<{
+        set(labels: Record<string, string>, value: number): void;
+    }>;
+    register: RegistryLike;
+}
+/** Options of `CachePrometheusModule.forRoot`. */
+interface CachePrometheusOptions {
+    /** The client module: `import * as client from 'prom-client'` or `'@prometheus-io/client'`. */
+    client: PrometheusClientLike;
+    /** Where the metrics are registered. Default `client.register`. */
+    registry?: RegistryLike;
+    /** Metric name prefix (not the cache key prefix). Default `'cache_'`. */
+    prefix?: string;
+    /** Histogram buckets in seconds, strictly increasing. Default: the client's default buckets. */
+    buckets?: readonly number[];
+}
+/** Options of `CachePrometheusModule.forRootAsync`: `useFactory` resolves the module options. */
+interface CachePrometheusAsyncOptions {
+    imports?: ModuleMetadata['imports'];
+    inject?: FactoryProvider['inject'];
+    useFactory: (...args: never[]) => CachePrometheusOptions | Promise<CachePrometheusOptions>;
+}
+
+/**
+ * Records cache metrics through a Prometheus client you pass in (`prom-client` or
+ * `@prometheus-io/client`). Needs a global `CacheModule`. Opens no endpoint.
+ */
+declare class CachePrometheusModule {
+    static forRoot(options: CachePrometheusOptions): DynamicModule;
+    static forRootAsync(options: CachePrometheusAsyncOptions): DynamicModule;
+}
+
+/**
+ * Traces cache calls through an OpenTelemetry tracer you pass in, for example
+ * `trace.getTracer('my-app')`; without this module nothing is traced. Needs a global
+ * `CacheModule`. Register it once: a second registration fails the app init with
+ * `CacheConfigError`.
+ */
+declare class CacheTracingModule {
+    /** Registers the tracer given up front. Invalid options throw `CacheConfigError`. */
+    static forRoot(options: CacheTracingOptions): DynamicModule;
+    /**
+     * Registers the tracer `useFactory` returns; it can inject providers. Invalid options fail
+     * the app init with `CacheConfigError`.
+     */
+    static forRootAsync(options: CacheTracingAsyncOptions): DynamicModule;
+}
+
+export { CacheConfigError, CacheEvents, CacheEvict, CacheHealthIndicator, CacheModule, CachePrometheusModule, CachePut, CacheService, CacheTracingModule, Cacheable, CircuitBreakerStore, CircuitOpenError, HttpCache, HttpCacheInterceptor, MemoryStore, RedisStore, TieredStore, circuitBreakerStore, compressedSerializer, ioredisAdapter, jsonSerializer, memoryStore, nodeRedisAdapter, redisInvalidationBus, redisStore, tieredStore };
+export type { BreakerState, CacheDefaults, CacheEnvelope, CacheEventMap, CacheEventSink, CacheEvictOptions, CacheHealthResult, CacheLockDefaults, CacheLogLevel, CacheModuleAsyncOptions, CacheModuleOptions, CacheOperation, CachePrometheusAsyncOptions, CachePrometheusOptions, CachePutOptions, CacheStore, CacheTracingAsyncOptions, CacheTracingOptions, CacheableOptions, CircuitBreakerStoreOptions, CompressedSerializerOptions, GetOrSetManyOptions, GetOrSetOptions, HttpCacheOptions, HttpCacheRequest, HttpCacheTags, InvalidationBus, InvalidationMessage, IoredisClusterLike, IoredisLike, KeyOptions, KeySpec, LoadStrategyOptions, LockHandle, LockProvider, MemoryStoreOptions, NodeRedisClusterLike, NodeRedisLike, NodeRedisSentinelLike, PrometheusClientLike, RedisClientAdapter, RedisInvalidationBusOptions, RedisStoreOptions, RedisSubscriberAdapter, RegistryLike, Serializer, SpanAttributeValue, SpanContextLike, SpanLike, SpanOptionsLike, StrategyOptions, TagSpec, TieredStoreOptions, TracerLike, WriteManyOptions, WriteOptions };