@bymax-one/nest-cache 1.1.0 → 1.2.0

package/dist/admin/index.d.ts

@@ -0,0 +1,967 @@
+import { DynamicModule, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
+import { CacheService, ResolvedOptions, ISerializer } from '@bymax-one/nest-cache';
+
+/**
+ * The keyspaces an administration surface is allowed to read, and what may be
+ * read from each.
+ *
+ * Layer: admin. A scope is declared by the *application*, not by the library and
+ * not by a caller. The library owns the mechanism — validating the declarations,
+ * scanning against them, withholding what they mark unreadable — while which
+ * keyspaces exist is a fact about a deployment's wiring that no library can
+ * learn. A cache configured with `namespace: 'app'` may still share its Redis
+ * with keys another library writes at root through `CacheService.getClient()`,
+ * and only the application knows that.
+ *
+ * @see `docs/technical_specification.md` §7 — Namespace Strategy
+ */
+/**
+ * One keyspace an administration surface may read.
+ *
+ * Declared once at module wiring and frozen. A caller names a scope by
+ * {@link CacheScope.id} and never supplies a pattern — a pattern composed from
+ * request input is the vulnerability class this type exists to close.
+ */
+interface CacheScope {
+    /** The identifier a caller names. Unique within a deployment; never a pattern. */
+    readonly id: string;
+    /** Human-readable name for an operator-facing surface. */
+    readonly label: string;
+    /**
+     * The `SCAN` match pattern this scope resolves to.
+     *
+     * Composed by the application and validated here: it must carry at least one
+     * literal character before its first glob metacharacter, so a scope can never
+     * resolve to the whole keyspace. That is an anchoring guarantee, not a
+     * narrowness one — the library cannot judge whether `a*` is too broad for a
+     * given deployment, only that it is anchored somewhere.
+     */
+    readonly pattern: string;
+    /**
+     * Whether a key's **value** may be returned from this scope.
+     *
+     * `false` means the value alone is withheld. Listing, types, TTLs and sizes
+     * stay available, and that split is the whole point: a surface that renders an
+     * unreadable keyspace as empty tells an operator the region holds nothing when
+     * it is full — the same defect as a blank log page during an outage, where a
+     * reading meaning "I may not tell you" is drawn identically to one meaning
+     * "there is nothing here".
+     */
+    readonly isReadable: boolean;
+    /**
+     * Why this keyspace exists, in the application's own words.
+     *
+     * Rendered **verbatim**, as plain text — the library imposes no length limit
+     * and interprets no markup. An application with one scope wants a sentence and
+     * one with eight wants a phrase, and a truncation rule imposed here would cut
+     * an explanation mid-clause on the screen where the explanation is the point.
+     */
+    readonly origin: string;
+}
+
+/**
+ * Options for the administration module.
+ *
+ * Layer: admin. The application declares which keyspaces exist and how patient
+ * this deployment is; the library owns everything else.
+ */
+
+/** Consumer-supplied options for `BymaxCacheAdminModule`. */
+interface BymaxCacheAdminModuleOptions {
+    /**
+     * The keyspaces this deployment exposes, in the order a surface should offer
+     * them. Validated and frozen at wiring — see `validateScopes`.
+     */
+    scopes: readonly CacheScope[];
+    /** Round trip above which health reports `degraded`. Default: 250 ms. */
+    degradedAboveMs?: number;
+    /** How long a health probe waits before reporting `down`. Default: 2000 ms. */
+    probeTimeoutMs?: number;
+    /** Most keys one listing reads before reporting the page incomplete. Default: 500. */
+    scanLimit?: number;
+    /** Most commands one pipeline flush sends. Default: 100. */
+    commandBatchLimit?: number;
+    /** Most members or hash fields one value reveal returns. Default: 200. */
+    revealLimit?: number;
+    /** Most characters one revealed string value carries. Default: 4096. */
+    revealStringLimit?: number;
+    /** Register the module globally. Default: `false` — an admin surface is wired where it is used. */
+    isGlobal?: boolean;
+}
+
+/**
+ * Async wiring for {@link BymaxCacheAdminModule.forRootAsync}.
+ *
+ * `isGlobal` is a top-level field rather than part of the factory's result
+ * because Nest needs the `global` flag while building the module definition,
+ * which is before any async factory has resolved.
+ */
+interface BymaxCacheAdminModuleAsyncOptions {
+    /** Modules exporting whatever the factory injects. */
+    imports?: DynamicModule['imports'];
+    /** Providers injected into the factory. */
+    inject?: (InjectionToken | OptionalFactoryDependency)[];
+    /** Builds the administration options. */
+    useFactory: (...args: never[]) => BymaxCacheAdminModuleOptions | Promise<BymaxCacheAdminModuleOptions>;
+    /** Register globally. Decided synchronously; default `false`. */
+    isGlobal?: boolean;
+}
+/** Read-only administration for `@bymax-one/nest-cache`. */
+declare class BymaxCacheAdminModule {
+    /**
+     * Registers the administration surface with statically known options.
+     *
+     * Options are validated here, at wiring — a malformed scope or a non-positive
+     * threshold fails the boot rather than the first request.
+     *
+     * @param options - The scopes this deployment exposes, plus any thresholds.
+     * @returns The dynamic module.
+     * @throws {CacheException} `INVALID_SCOPE` when the declaration is malformed.
+     */
+    static forRoot(options: BymaxCacheAdminModuleOptions): DynamicModule;
+    /**
+     * Registers the administration surface with options built asynchronously.
+     *
+     * Validation runs inside the factory, so the same rules apply on both paths
+     * and neither can drift into accepting what the other rejects.
+     *
+     * @param options - Factory wiring plus the synchronous `isGlobal` flag.
+     * @returns The dynamic module.
+     */
+    static forRootAsync(options: BymaxCacheAdminModuleAsyncOptions): DynamicModule;
+}
+
+/** Administration options after defaults are merged and validated. */
+interface ResolvedAdminOptions {
+    readonly scopes: readonly CacheScope[];
+    readonly degradedAboveMs: number;
+    readonly probeTimeoutMs: number;
+    readonly scanLimit: number;
+    readonly commandBatchLimit: number;
+    readonly revealLimit: number;
+    readonly revealStringLimit: number;
+    readonly isGlobal: boolean;
+}
+/**
+ * Merges administration options with defaults, validates them, and freezes the
+ * result.
+ *
+ * @param options - The raw consumer options.
+ * @returns The frozen resolved options.
+ * @throws {CacheException} `INVALID_SCOPE` when a scope is malformed or a
+ *   threshold is not a positive integer.
+ */
+declare function resolveAdminOptions(options: BymaxCacheAdminModuleOptions): Readonly<ResolvedAdminOptions>;
+
+/**
+ * What an administration surface reads to decide what it can say about the cache.
+ *
+ * Layer: admin.
+ */
+/** How this deployment connects to Redis. */
+type CacheMode = 'standalone' | 'sentinel' | 'cluster';
+/**
+ * Why a probe did not answer.
+ *
+ * A closed union rather than the underlying error's text: an error message is
+ * free-form and may carry connection detail the library is careful never to
+ * echo (CLAUDE.md §4). The syscall {@link CacheProbeDown.code} carries the part
+ * an operator acts on; the full error reaches the application through the
+ * `ICacheEvents` hooks the module already provides.
+ */
+type CacheProbeFailure = 'timeout' | 'error';
+/** A probe that answered within the degraded threshold. */
+interface CacheProbeUp {
+    readonly status: 'up';
+    readonly latencyMs: number;
+}
+/** A probe that answered, but slowly. */
+interface CacheProbeDegraded {
+    readonly status: 'degraded';
+    readonly latencyMs: number;
+}
+/** A probe that did not answer. */
+interface CacheProbeDown {
+    readonly status: 'down';
+    readonly reason: CacheProbeFailure;
+    /** The syscall code when the driver reported one (`ECONNREFUSED`), else `null`. */
+    readonly code: string | null;
+}
+/**
+ * The result of pinging Redis.
+ *
+ * **Three states, not two.** A server answering `PING` slowly is neither up nor
+ * down, and collapsing it into either hides the state an operator most wants to
+ * catch early — by the time a slow cache becomes an unreachable one, the choice
+ * has been made for them.
+ *
+ * **A union, so `latencyMs` cannot exist without a measurement.** The invariant
+ * is that a latency is reported if and only if the ping answered; expressed as
+ * `latencyMs: number | null` it would be a convention, and a handler that caught
+ * a throwing ping and fell back to a default shape would hand a surface a
+ * confident status that really means "I did not ask" — undetectable from the
+ * payload. Here that shape does not typecheck.
+ */
+type CacheProbe = CacheProbeUp | CacheProbeDegraded | CacheProbeDown;
+/**
+ * The cache's health, as an administration surface reads it.
+ *
+ * `mode`, `isScanSupported` and `degradedAboveMs` sit OUTSIDE the discriminated
+ * part on purpose: a cluster deployment that is down should still report that
+ * scanning was never going to work, and folding those into the answering
+ * branches would make the `down` payload quieter about facts that have nothing
+ * to do with being down.
+ */
+type CacheHealth = CacheProbe & {
+    readonly mode: CacheMode;
+    /**
+     * Whether this deployment's mode supports `SCAN`.
+     *
+     * On the wire beside `mode` deliberately. The library refuses `scan` under
+     * cluster, and applying that rule is the library's job — a surface
+     * re-deriving it from `mode` would hold a copy of a rule it cannot see change.
+     */
+    readonly isScanSupported: boolean;
+    /** The round trip above which this deployment calls the cache degraded. */
+    readonly degradedAboveMs: number;
+};
+/** The resolved wiring, with every credential-bearing field withheld. */
+interface CacheConfig {
+    readonly mode: CacheMode;
+    readonly namespace: string;
+    readonly keySeparator: string;
+    readonly shutdownTimeoutMs: number;
+    readonly isFlushAllowedInProduction: boolean;
+    /** The serializer's constructor name, or `null` when it does not report one. */
+    readonly serializer: string | null;
+    /** The Lua scripts registered at wiring, by name only — never their bodies. */
+    readonly scripts: readonly string[];
+    /**
+     * Where this deployment connects, with the connection URL withheld.
+     *
+     * `ResolvedOptions.connection` is `{ url, password, ... }`, so serving the
+     * resolved options directly — the obvious implementation — ships a Redis URL
+     * with its password to whatever reads this. Host, port and a TLS flag carry
+     * everything an operator-facing panel needs and none of the credential.
+     *
+     * `host` and `port` are `null` under sentinel and cluster, where there is no
+     * single endpoint to name; `mode` alongside says why.
+     */
+    readonly connection: {
+        readonly host: string | null;
+        readonly port: number | null;
+        readonly isTls: boolean;
+    };
+}
+
+/**
+ * The `INFO` subset an administration surface reads.
+ *
+ * Layer: admin. Every field here is reported, never defaulted: a value this
+ * server does not publish arrives as `null` and a surface renders "not
+ * reported". Substituting a zero would draw a reading that means "I could not
+ * measure" identically to one that means "I measured, and it is nothing".
+ *
+ * Where a single `null` would carry two different meanings, the type is a
+ * discriminated union instead — see {@link MaxMemory}.
+ */
+/**
+ * The configured memory ceiling.
+ *
+ * A union rather than `number | null` because `maxmemory` has three states and
+ * only two of them are a number. Redis spells "no ceiling" as `maxmemory:0`,
+ * which read as a literal ceiling makes a saturation bar show full on the least
+ * constrained server there is; and a server that does not publish the field at
+ * all has told us nothing. Collapsing "unbounded" and "unreported" into one
+ * `null` leaves a surface unable to tell an operator which of those it is
+ * looking at, and they call for opposite actions.
+ */
+type MaxMemory = 
+/** A ceiling is configured. */
+{
+    readonly kind: 'limited';
+    readonly bytes: number;
+}
+/** `maxmemory:0` — the server will grow until the host stops it. */
+ | {
+    readonly kind: 'unbounded';
+}
+/** The server does not publish `maxmemory`. */
+ | {
+    readonly kind: 'unreported';
+};
+/** The outcome of the most recent background save, or `null` when unreported. */
+type BgsaveStatus = 'ok' | 'err' | null;
+/** Whether this server is a primary or a replica. */
+type ReplicationRole = 'master' | 'replica';
+/** A parsed reading of Redis `INFO`. */
+interface RedisStats {
+    /**
+     * When this reading was taken, by the **reading host's** clock — not the
+     * Redis server's.
+     *
+     * Named for the side that measured it. Under clock skew between the
+     * application host and the Redis host the two differ, and this value is used
+     * to place a reading on an incident timeline, which is exactly where the
+     * difference shows.
+     */
+    readonly readAt: string;
+    readonly server: {
+        readonly redisVersion: string | null;
+        readonly mode: string | null;
+        readonly uptimeSeconds: number | null;
+    };
+    readonly clients: {
+        readonly connected: number | null;
+        readonly blocked: number | null;
+    };
+    readonly memory: {
+        readonly usedBytes: number | null;
+        readonly peakBytes: number | null;
+        /** Three-state: a ceiling, no ceiling, or no answer. See {@link MaxMemory}. */
+        readonly max: MaxMemory;
+        /**
+         * Allocator fragmentation, reported raw.
+         *
+         * Interpretation is deliberately left to the caller: on an instance holding
+         * very little, allocator and copy-on-write overhead dominate and this reads
+         * far above 1 without indicating a problem — 9.07 was measured on an
+         * instance holding 1.1 MiB. A threshold that turns this into a health
+         * verdict is deployment policy, not a property of the reading.
+         */
+        readonly fragmentationRatio: number | null;
+        readonly evictionPolicy: string | null;
+    };
+    readonly stats: {
+        readonly keyspaceHits: number | null;
+        readonly keyspaceMisses: number | null;
+        readonly expiredKeys: number | null;
+        readonly evictedKeys: number | null;
+        readonly instantaneousOpsPerSec: number | null;
+        readonly totalCommandsProcessed: number | null;
+        readonly totalConnectionsReceived: number | null;
+        readonly rejectedConnections: number | null;
+    };
+    readonly persistence: {
+        readonly rdbLastSaveAt: string | null;
+        readonly rdbChangesSinceLastSave: number | null;
+        readonly rdbLastBgsaveStatus: BgsaveStatus;
+        /**
+         * Whether append-only persistence is on, or `null` when the server does not
+         * publish `aof_enabled`.
+         *
+         * Nullable rather than defaulting to `false`, because `false` here is a
+         * claim about durability made in the absence of evidence — "AOF is off" and
+         * "I could not determine whether AOF is on" are different sentences to
+         * someone deciding whether a restart loses writes.
+         */
+        readonly aofEnabled: boolean | null;
+    };
+    readonly replication: {
+        readonly role: ReplicationRole;
+        readonly connectedReplicas: number | null;
+    };
+}
+
+/**
+ * The cache capabilities this service reads through.
+ *
+ * A `Pick` of the real facade rather than the class itself: Nest still injects
+ * the concrete `CacheService`, while a test supplies a plain object with two
+ * methods and no cast. A cast would be a blocking finding under this
+ * repository's suppression policy, so the narrow type is not a convenience.
+ */
+type ICacheProbe = Pick<CacheService, 'ping' | 'info'>;
+/** Reports whether the cache is answering, what it is doing, and how it is wired. */
+declare class CacheStatusService {
+    private readonly cache;
+    private readonly options;
+    private readonly adminOptions;
+    private readonly serializer;
+    /**
+     * @param cache - The cache facade this service probes through.
+     * @param options - The resolved cache module options.
+     * @param adminOptions - The resolved administration options.
+     * @param serializer - The wired serializer, named on the config payload.
+     */
+    constructor(cache: ICacheProbe, options: ResolvedOptions, adminOptions: ResolvedAdminOptions, serializer: ISerializer);
+    /**
+     * Pings Redis and reports the result in three states.
+     *
+     * @returns The probe outcome, plus the mode facts that hold whether or not it
+     *   answered.
+     */
+    health(): Promise<CacheHealth>;
+    /**
+     * Reads Redis `INFO` into a typed reading.
+     *
+     * @returns The parsed statistics, stamped with the reading host's clock.
+     */
+    stats(): Promise<RedisStats>;
+    /**
+     * Reports how this deployment is wired, with every credential withheld.
+     *
+     * @returns The resolved configuration, safe to serve to an operator surface.
+     */
+    config(): CacheConfig;
+    /**
+     * Measures one `PING`.
+     *
+     * `latencyMs` is produced on exactly one path — a reply that arrived. Every
+     * other outcome returns the `down` branch, which has no latency field to fill
+     * in, so a confident status without a measurement cannot be constructed here.
+     *
+     * @returns The probe outcome.
+     */
+    private probe;
+}
+
+/**
+ * The Redis commands the administration surface issues.
+ *
+ * Layer: admin. Declared as capabilities rather than taken as ioredis's `Redis`
+ * so a unit test can supply a plain object with no cast — a cast would be a
+ * blocking finding under this repository's suppression policy, making the narrow
+ * interface a correctness requirement rather than a convenience. The real client
+ * satisfies these structurally, which a compile-time check in the service pins.
+ *
+ * **Every command named here is read-only.** No `DEL`, no `SET`, no `EXPIRE`, no
+ * `UNLINK`, no `FLUSHDB`. That is worth stating because the client this surface
+ * holds can do all of them — and it is enforced rather than asserted: the
+ * `check:admin-readonly` gate fails the build if a mutating command appears in
+ * this subpath.
+ */
+/** One entry of a pipeline's result: an error, or a value. */
+type PipelineReply = [Error | null, unknown];
+/** A pipeline being composed, chainable the way ioredis's commander is. */
+interface IRedisPipeline {
+    /** Queues `TYPE`. */
+    type(key: string): IRedisPipeline;
+    /** Queues `TTL`. */
+    ttl(key: string): IRedisPipeline;
+    /** Queues `MEMORY USAGE`. */
+    memory(subcommand: 'USAGE', key: string): IRedisPipeline;
+    /** Sends the batch. */
+    exec(): Promise<PipelineReply[] | null>;
+}
+/** The subset of the Redis client this surface reads through. */
+interface IRedisReader {
+    /** Cursor-based key iteration. */
+    scan(cursor: string | number, matchToken: 'MATCH', pattern: string, countToken: 'COUNT', count: number | string): Promise<[string, string[]]>;
+    /** Opens a batch. */
+    pipeline(): IRedisPipeline;
+    /** Reads one key's type. */
+    type(key: string): Promise<string>;
+    /** Reads one key's remaining life in seconds. */
+    ttl(key: string): Promise<number>;
+    /** Reads a string's value. */
+    get(key: string): Promise<string | null>;
+    /** Reads a hash's fields. */
+    hgetall(key: string): Promise<Record<string, string>>;
+    /** Reads a set's members. */
+    smembers(key: string): Promise<string[]>;
+    /** Reads a slice of a list. */
+    lrange(key: string, start: number, stop: number): Promise<string[]>;
+    /**
+     * Sends a command by name.
+     *
+     * Present for the one read this interface cannot express as a method:
+     * ioredis's `zrange` overload set cannot be narrowed to a four-argument
+     * signature (measured — TypeScript resolves the assignment against a nine
+     * argument overload and rejects it), so the sorted-set read goes through here
+     * as `ZRANGE key start stop WITHSCORES`.
+     *
+     * It is a general escape hatch, which is exactly why the `check:admin-readonly`
+     * gate inspects the command names this subpath passes to it rather than
+     * trusting that only reads are sent.
+     */
+    call(command: string, ...args: (string | number)[]): Promise<unknown>;
+}
+/** How the administration surface obtains its reader. */
+interface IRedisReaderSource {
+    /**
+     * Returns the client.
+     *
+     * The library's own `CacheService.getClient()` refuses cluster mode with
+     * `cache.unsupported_in_cluster`, so the cluster refusal this surface needs
+     * comes from the same rule the rest of the library applies rather than a
+     * second copy of it.
+     */
+    getClient(): IRedisReader;
+}
+
+/**
+ * The shapes an administration surface reads about keys.
+ *
+ * Layer: admin. As in {@link ../types/redis-stats.types}, a value that would
+ * carry two meanings under one `null` is a discriminated union instead.
+ */
+/**
+ * The Redis data types this surface names, plus an escape hatch.
+ *
+ * `other` is what makes the union safe to declare closed. Redis may report a
+ * type this build has never heard of — a module type, or one added by a later
+ * server — and mapping the unrecognised case to a named member means a
+ * consumer's exhaustive switch can never be wrong about a real reply. Passing
+ * the raw string through instead would put an open set into a closed type.
+ */
+type RedisKeyType = 'string' | 'hash' | 'set' | 'list' | 'zset' | 'stream' | 'other';
+/**
+ * How much life a key has left.
+ *
+ * A union rather than `number | null`, because Redis answers `TTL` with three
+ * distinct facts and two of them are not a number: `-1` means the key exists
+ * with no expiry, and `-2` means the key does not exist. Collapsing those into
+ * one `null` forces the caller to recover the difference from somewhere else —
+ * and the case where it matters most is a key that expired between the scan and
+ * the read, which is exactly the key an operator is staring at when they care.
+ */
+type KeyTtl = 
+/** The key expires in `seconds`. */
+{
+    readonly kind: 'expiring';
+    readonly seconds: number;
+}
+/** The key exists and has no expiry set (`TTL` → `-1`). */
+ | {
+    readonly kind: 'persistent';
+}
+/** The key does not exist (`TTL` → `-2`). */
+ | {
+    readonly kind: 'missing';
+};
+/** One key as it appears in a listing. */
+interface KeyEntry {
+    /** The full key, exactly as Redis stores it. */
+    readonly key: string;
+    readonly type: RedisKeyType;
+    readonly ttl: KeyTtl;
+    /**
+     * Serialized size in bytes, or `null` when not measured.
+     *
+     * `null` covers two cases the caller can already tell apart from the request
+     * it made: sizing was not requested, or the server declined to answer for this
+     * key. Reporting `0` instead would make a key of unknown size and a key
+     * occupying nothing render identically, and only one of them is a measurement.
+     */
+    readonly sizeBytes: number | null;
+}
+/** One page of a keyspace listing. */
+interface KeyspacePage {
+    /** The scope this page was read from. */
+    readonly scopeId: string;
+    readonly entries: readonly KeyEntry[];
+    /**
+     * How many keys this page actually read.
+     *
+     * Named `sampled` rather than `count` because it is a sum over a capped
+     * `SCAN`, not a measurement of the keyspace. {@link KeyspacePage.isComplete}
+     * is the fact; the name is the guard — a caller reaching for one of these does
+     * not necessarily read the other, and a bare `count` would look measured.
+     */
+    readonly sampledCount: number;
+    /**
+     * Total serialized bytes across the keys whose size was measured, or `null`
+     * when sizing was not requested.
+     *
+     * Sampled for the same reason as {@link KeyspacePage.sampledCount}, and
+     * renamed with it or not at all — moving only one of the pair relocates the
+     * trap instead of closing it.
+     */
+    readonly sampledBytes: number | null;
+    /** Whether the scan reached the end of the scope rather than the cap. */
+    readonly isComplete: boolean;
+    /** The cap this page was read under, so a caller can say why it stopped. */
+    readonly scanLimit: number;
+    /** Cursor to continue from, or `null` when the scope was exhausted. */
+    readonly cursor: string | null;
+}
+/** One key, described without reading its value. */
+interface KeyDetail extends KeyEntry {
+    /** The scope the key was resolved through. */
+    readonly scopeId: string;
+    /**
+     * Whether this scope permits reading the key's value.
+     *
+     * Present on the detail so a surface can render the listing honestly and
+     * disable only the reveal, rather than discovering the refusal by attempting it.
+     */
+    readonly isReadable: boolean;
+}
+/** A revealed value, shaped by the key's Redis type. */
+type RevealedValue = {
+    readonly kind: 'string';
+    readonly value: string;
+    readonly isComplete: boolean;
+} | {
+    readonly kind: 'hash';
+    readonly fields: readonly {
+        readonly name: string;
+        readonly value: string;
+    }[];
+    readonly isComplete: boolean;
+}
+/** Sets and lists: a flat member list. The enclosing `type` says which it is. */
+ | {
+    readonly kind: 'members';
+    readonly members: readonly string[];
+    readonly isComplete: boolean;
+} | {
+    readonly kind: 'scored';
+    readonly members: readonly {
+        readonly member: string;
+        readonly score: string;
+    }[];
+    readonly isComplete: boolean;
+}
+/** A type this surface does not render — streams, module types. */
+ | {
+    readonly kind: 'unsupported';
+    readonly type: RedisKeyType;
+};
+/**
+ * The outcome of asking for a key's value.
+ *
+ * A discriminated union rather than a nullable value, because `withheld` and
+ * `missing` are different answers and rendering them identically is the defect
+ * this whole surface exists to avoid: one means "I may not tell you", the other
+ * means "there is nothing here".
+ */
+type RevealResult = {
+    readonly status: 'revealed';
+    readonly key: string;
+    readonly type: RedisKeyType;
+    readonly value: RevealedValue;
+}
+/**
+ * The scope withholds values. Listing, types, TTLs and sizes remain available
+ * for this key — only the value is refused, and `origin` says why in the
+ * application's own words.
+ */
+ | {
+    readonly status: 'withheld';
+    readonly key: string;
+    readonly scopeId: string;
+    readonly origin: string;
+}
+/** The key does not exist. */
+ | {
+    readonly status: 'missing';
+    readonly key: string;
+};
+
+/** Options for one keyspace listing. */
+interface ListKeysOptions {
+    /** Cursor from a previous page; omit to start at the beginning of the scope. */
+    cursor?: string;
+    /**
+     * Measure each key's serialized size.
+     *
+     * Opt-in because it is not free: it adds a `MEMORY USAGE` per key, and Redis
+     * is single-threaded, so the cost lands on every other client waiting behind
+     * the batch — on a server an operator is inspecting precisely because it is
+     * unwell.
+     */
+    includeSize?: boolean;
+}
+/** Reads the keyspace an administration surface is allowed to see. */
+declare class CacheAdminService {
+    private readonly cache;
+    private readonly options;
+    /**
+     * @param cache - Supplies the client. `CacheService.getClient()` refuses
+     *   cluster mode, so this surface inherits that rule rather than restating it.
+     * @param options - The resolved administration options.
+     */
+    constructor(cache: IRedisReaderSource, options: ResolvedAdminOptions);
+    /**
+     * Returns the declared scopes.
+     *
+     * **Never touches the connection**, and that is a property rather than an
+     * accident of the current implementation. A surface reads this to decide what
+     * it may offer at all, so it must answer during an outage — an operator whose
+     * cache is down is exactly the person who needs to be told what the inspector
+     * covers. The tempting change is a liveness check to make the list "more
+     * accurate"; it would turn a declaration into a measurement, and a scope that
+     * vanished during an outage reads as a scope that was removed.
+     *
+     * @returns The frozen allowlist, in declaration order.
+     */
+    listScopes(): readonly CacheScope[];
+    /**
+     * Lists one page of the keys in a scope.
+     *
+     * The page may carry slightly MORE than `scanLimit` entries: the limit stops
+     * the scan loop, and the batch that crosses it is kept whole rather than
+     * trimmed, because the cursor has already moved past those keys and trimming
+     * would drop them from every subsequent page too.
+     *
+     * @param scopeId - The scope a caller named.
+     * @param listOptions - Cursor and whether to measure sizes.
+     * @returns The page, with the sample it read and whether it reached the end.
+     * @throws {CacheException} `SCOPE_NOT_FOUND` for an undeclared id, or
+     *   `UNSUPPORTED_IN_CLUSTER` in cluster mode.
+     */
+    listKeys(scopeId: string, listOptions?: ListKeysOptions): Promise<KeyspacePage>;
+    /**
+     * Describes one key without reading its value.
+     *
+     * Works on an unreadable scope: only the value is withheld, never the
+     * description. {@link KeyDetail.isReadable} lets a surface disable the reveal
+     * rather than discovering the refusal by attempting it.
+     *
+     * @param scopeId - The scope a caller named.
+     * @param key - The key, which must belong to that scope.
+     * @returns The key's type, remaining life, and whether its value may be read.
+     * @throws {CacheException} `SCOPE_NOT_FOUND` or `KEY_NOT_IN_SCOPE`.
+     */
+    describeKey(scopeId: string, key: string): Promise<KeyDetail>;
+    /**
+     * Reads a key's value, or explains why it will not.
+     *
+     * @param scopeId - The scope a caller named.
+     * @param key - The key, which must belong to that scope.
+     * @returns The value, a refusal carrying the scope's `origin`, or `missing`.
+     * @throws {CacheException} `SCOPE_NOT_FOUND` or `KEY_NOT_IN_SCOPE`.
+     */
+    revealValue(scopeId: string, key: string): Promise<RevealResult>;
+    /**
+     * Resolves a scope and confirms the key belongs to it.
+     *
+     * The membership check is the reason scope patterns are restricted to a
+     * literal prefix: it makes this decidable exactly, rather than by a matcher
+     * that could be more permissive than the server's.
+     *
+     * @param scopeId - The scope a caller named.
+     * @param key - The key a caller named.
+     * @returns The resolved scope.
+     * @throws {CacheException} `SCOPE_NOT_FOUND` or `KEY_NOT_IN_SCOPE`.
+     */
+    private resolve;
+    /**
+     * Describes every key on a page, in batches bounded by command count.
+     *
+     * The bound is in commands rather than keys because that is the resource
+     * actually spent: describing a key costs two commands, or three when sized,
+     * and Redis works through a flush single-threaded while every other client
+     * waits. At least one key goes per batch, so a limit below one key's cost
+     * still makes progress instead of dividing to nothing.
+     *
+     * @param client - The reader.
+     * @param keys - The page's keys.
+     * @param includeSize - Whether to add `MEMORY USAGE`.
+     * @returns One entry per key, in page order.
+     */
+    private describeAll;
+    /**
+     * Reads a value according to its Redis type, truncating to the configured caps.
+     *
+     * @param client - The reader.
+     * @param key - The key to read.
+     * @param type - The key's type.
+     * @returns The value, or `null` when the key vanished between reads.
+     */
+    private readValue;
+}
+
+/**
+ * Splits a validated pattern into the literal prefix a key must carry and
+ * whether that prefix may be extended.
+ *
+ * @param pattern - A pattern that already satisfies {@link SCOPE_PATTERN_SHAPE}.
+ * @returns The literal prefix, and whether a trailing `*` allows a suffix.
+ */
+declare function readScopePattern(pattern: string): {
+    readonly prefix: string;
+    readonly isPrefixMatch: boolean;
+};
+/**
+ * Reports whether a key falls inside a scope's declared region.
+ *
+ * Exact by construction rather than by matching — see {@link SCOPE_PATTERN_SHAPE}
+ * for why the pattern shape is restricted to make this possible.
+ *
+ * @param pattern - The scope's validated match pattern.
+ * @param key - The key a caller named.
+ * @returns `true` when the key belongs to the scope.
+ */
+declare function isKeyInScope(pattern: string, key: string): boolean;
+/**
+ * Validates an administration scope allowlist and returns a frozen copy.
+ *
+ * Every rule here closes a way the allowlist could authorise more than it
+ * appears to: an unanchored pattern reaches the whole instance, a duplicate id
+ * makes one declaration silently shadow another, and an empty field produces a
+ * scope a surface can name but not explain. Freezing the result keeps the
+ * decision made at wiring from being edited by anything that later holds it.
+ *
+ * @param scopes - The scopes the application declares.
+ * @returns A frozen list of frozen scopes, in declaration order.
+ * @throws {CacheException} `INVALID_SCOPE` when the list is empty, a required
+ *   field is empty, an id repeats, or a pattern has no literal prefix.
+ */
+declare function validateScopes(scopes: readonly CacheScope[]): readonly CacheScope[];
+/**
+ * Finds a declared scope by the identifier a caller named.
+ *
+ * Exact string equality against the frozen list, never interpolation — the
+ * caller's input selects a declaration, it never contributes to one.
+ *
+ * @param scopes - The validated allowlist.
+ * @param id - The identifier from the request.
+ * @returns The scope.
+ * @throws {CacheException} `SCOPE_NOT_FOUND` when no declaration has that id.
+ */
+declare function findScope(scopes: readonly CacheScope[], id: string): CacheScope;
+
+/**
+ * Reads Redis `INFO` text into a typed reading.
+ *
+ * Layer: admin. `INFO` is section headers (`# Memory`), `field:value` lines and
+ * blank lines separated by CRLF. Every value arrives as text — a count, a ratio
+ * and a Unix timestamp are indistinguishable until something decides which is
+ * which, and that decision is this module's whole content.
+ *
+ * Parsed here rather than by each consumer: the format is a wire detail, and
+ * interpreting it once on the side that can be tested against a real server
+ * beats every surface holding its own copy of the rules.
+ *
+ * The field names are asserted against a real Redis in the E2E suite rather than
+ * taken from documentation. A Redis test double returns whatever its fixture
+ * decided, so every name here would pass a unit suite while being wrong — a
+ * double cannot falsify an assumption about the thing it stands in for.
+ */
+
+/**
+ * Splits `INFO` text into its fields.
+ *
+ * Section headers are dropped rather than used to namespace the fields: `INFO`
+ * field names are already unique across sections, and keying by section would
+ * make this depend on header spellings that vary between versions while the
+ * field names do not.
+ *
+ * @param text - The raw `INFO` output.
+ * @returns Field name to raw text value.
+ */
+declare function parseInfoFields(text: string): ReadonlyMap<string, string>;
+/**
+ * Turns `INFO` text into a typed reading.
+ *
+ * @param infoText - The raw `INFO` output.
+ * @param readAt - When the reading was taken, by the reading host's clock.
+ * @returns The parsed statistics.
+ */
+declare function readRedisStats(infoText: string, readAt: Date): RedisStats;
+
+/**
+ * Narrowing of raw Redis replies into the admin surface's typed readings.
+ *
+ * Layer: admin. ioredis hands back `unknown` for the commands this surface
+ * issues through a pipeline, and every reply that reaches a caller passes
+ * through here first. Each helper reports absence rather than substituting a
+ * value that would read as a measurement.
+ */
+
+/**
+ * Narrows a `TYPE` reply to the closed union.
+ *
+ * @param reply - Whatever the server answered.
+ * @returns The recognised type, or `other`.
+ */
+declare function readKeyType(reply: unknown): RedisKeyType;
+/**
+ * Narrows a `TTL` reply to its three distinct meanings.
+ *
+ * A reply that is not a number, or is a negative value Redis does not document,
+ * is reported as `missing` rather than as a remaining life — a negative
+ * countdown on a screen is a reading no server produced.
+ *
+ * @param reply - Whatever the server answered.
+ * @returns Whether the key expires, is persistent, or is gone.
+ */
+declare function readKeyTtl(reply: unknown): KeyTtl;
+/**
+ * Narrows a `MEMORY USAGE` reply.
+ *
+ * Reports `null` rather than zero when the server declines to answer: a key
+ * whose size is genuinely unknown and one that occupies nothing render the same
+ * under a zero, and only one of them is a measurement.
+ *
+ * @param reply - Whatever the server answered.
+ * @returns The size in bytes, or `null` when no size was reported.
+ */
+declare function readSizeBytes(reply: unknown): number | null;
+
+/**
+ * NestJS injection tokens for the `@bymax-one/nest-cache/admin` subpath.
+ *
+ * Layer: admin. `Symbol`-based for the same reason as the server tokens: two
+ * consumers cannot collide by accident, and a string typo cannot resolve a
+ * foreign provider.
+ */
+/** Resolved administration options (scopes, thresholds, limits). */
+declare const BYMAX_CACHE_ADMIN_OPTIONS: unique symbol;
+
+/**
+ * Defaults for the administration surface.
+ *
+ * Layer: admin. Each value is a threshold a deployment may override; they live
+ * together so a consumer reading one can see what else is tunable.
+ */
+/**
+ * Round trip above which the cache is answering but not well.
+ *
+ * A round number rather than a measured percentile, and deliberately so: this is
+ * the threshold at which a surface changes what it reports, not a service-level
+ * objective. A cache taking this long has stopped being the thing that makes
+ * requests fast.
+ */
+declare const DEFAULT_DEGRADED_ABOVE_MS = 250;
+/**
+ * How long a health probe waits before reporting the cache down.
+ *
+ * Without this, a `PING` against a wedged connection never settles and a health
+ * route hangs instead of answering — the failure mode a health route exists to
+ * report becomes the failure mode it exhibits.
+ */
+declare const DEFAULT_PROBE_TIMEOUT_MS = 2000;
+/**
+ * Most keys a single listing reads before reporting the page incomplete.
+ *
+ * A cap rather than a full scan: an administration surface asks about keyspaces
+ * whose size is exactly what it does not know yet.
+ */
+declare const DEFAULT_SCAN_LIMIT = 500;
+/**
+ * Most commands one pipeline flush sends.
+ *
+ * Bounds the BATCH, in commands, rather than the key count — that is the
+ * resource actually spent. Redis is single-threaded, so a pipeline converts a
+ * network cost into a server-blocking one: describing N keys is two or three
+ * commands each, and sending them as one flush blocks every other client for
+ * the whole burst — on a server someone is inspecting precisely because it is
+ * unwell. Pipelining is the aggravating factor here, not the mitigation.
+ *
+ * Every batch chunks to this size regardless of how many keys the page allows,
+ * so a permitted maximum arrives as several small blocks rather than one large
+ * one.
+ */
+declare const DEFAULT_COMMAND_BATCH_LIMIT = 100;
+/**
+ * Most members or hash fields one value reveal returns.
+ *
+ * A reveal is a debugging read, not an export. Returning a million-member set
+ * would block the server assembling it and hand a surface a payload it cannot
+ * draw; the truncation is reported so nobody mistakes the page for the whole.
+ */
+declare const DEFAULT_REVEAL_LIMIT = 200;
+/**
+ * Most characters one revealed string value carries.
+ *
+ * Same reasoning as {@link DEFAULT_REVEAL_LIMIT}: a cached HTML document or a
+ * serialized blob is measured in megabytes, and a surface asking "what is in
+ * this key" does not need all of it to answer the question.
+ */
+declare const DEFAULT_REVEAL_STRING_LIMIT = 4096;
+
+export { BYMAX_CACHE_ADMIN_OPTIONS, type BgsaveStatus, BymaxCacheAdminModule, type BymaxCacheAdminModuleAsyncOptions, type BymaxCacheAdminModuleOptions, CacheAdminService, type CacheConfig, type CacheHealth, type CacheMode, type CacheProbe, type CacheProbeDegraded, type CacheProbeDown, type CacheProbeFailure, type CacheProbeUp, type CacheScope, CacheStatusService, DEFAULT_COMMAND_BATCH_LIMIT, DEFAULT_DEGRADED_ABOVE_MS, DEFAULT_PROBE_TIMEOUT_MS, DEFAULT_REVEAL_LIMIT, DEFAULT_REVEAL_STRING_LIMIT, DEFAULT_SCAN_LIMIT, type ICacheProbe, type IRedisPipeline, type IRedisReader, type IRedisReaderSource, type KeyDetail, type KeyEntry, type KeyTtl, type KeyspacePage, type ListKeysOptions, type MaxMemory, type PipelineReply, type RedisKeyType, type RedisStats, type ReplicationRole, type ResolvedAdminOptions, type RevealResult, type RevealedValue, findScope, isKeyInScope, parseInfoFields, readKeyTtl, readKeyType, readRedisStats, readScopePattern, readSizeBytes, resolveAdminOptions, validateScopes };