bazis 0.98.33 → 0.99.0

package/core/cache/SPEC.md

@@ -19,7 +19,7 @@ Quick navigation:
 - [7. `@OutputRedisCache` — HTTP output cache (distributed)](#7-outputrediscache--http-output-cache-distributed)
 - [8. `@Cacheable`: service method cache (memory)](#8-cacheable-service-method-cache-memory)
 - [9. `@CacheableRedis`: service method cache (distributed)](#9-cacheableredis-service-method-cache-distributed)
-- [10. DI providers: `cachedSingleton` / `cachedScoped` (+ auto-hook)](#10-di-providers-cachedsingleton--cachedscoped--auto-hook)
+- [10. DI registration: `singleton` / `scoped` with the cache hook](#10-di-registration-singleton--scoped-with-the-cache-hook)
 - [11. `ICache`: programmatic API](#11-icache-programmatic-api)
 - [12. Output cache key building](#12-output-cache-key-building)
 - [13. Anti-stampede and concurrent miss](#13-anti-stampede-and-concurrent-miss)
@@ -68,7 +68,6 @@ import {
   OutputRedisCache,
   Cacheable,
   CacheableRedis,
-  cachedScoped,
   ICache,
 } from "@/core/cache";
 import { composeRouteMiddlewareComposers } from "@/core/http";
@@ -116,8 +115,8 @@ import { redisConnect } from "@/core/infra";
 | --- | --- | --- | --- |
 | `@OutputCache` | controller action | `ICache` in-memory | the cache module's `ROUTE_MIDDLEWARE_COMPOSER` registration (automatic) |
 | `@OutputRedisCache` | controller action | `IDistributedCache` | the same + `redisConnect(config, { cache: "distributed" })` in Infra |
-| `@Cacheable` | service method | `ICache` in-memory | `cachedSingleton` / `cachedScoped` (or the auto-hook) |
-| `@CacheableRedis` | service method | `IDistributedCache` | `cachedSingleton` / `cachedScoped` + `redisConnect(config, { cache: "distributed" })` in Infra |
+| `@Cacheable` | service method | `ICache` in-memory | `singleton` / `scoped` (the cache hook wraps it) |
+| `@CacheableRedis` | service method | `IDistributedCache` | `singleton` / `scoped` + `redisConnect(config, { cache: "distributed" })` in Infra |
 
 **Important:** put decorators on the **implementation class**, not on a TypeScript interface. DI registers the interface token → the proxy wraps the implementation.
 
@@ -161,7 +160,7 @@ flowchart TB
 ### 3.1. Minimum: in-memory output + method cache
 
 ```ts
-import { Cacheable, OutputCache, cachedScoped, memory } from "@/core/cache";
+import { Cacheable, OutputCache, memory } from "@/core/cache";
 import { runApp } from "@/core/app";
 
 await runApp(AppModule, {
@@ -195,7 +194,7 @@ class UserService implements IUserStore {
 
 // UsersModule:
 providers: [
-  cachedScoped(IUserStore, UserService, [repositoryFor(User)]),
+  scoped(IUserStore, UserService, [repositoryFor(User)]),
 ],
 ```
 
@@ -232,7 +231,7 @@ class ProductService {
 
 // The same provider as for memory: the distributed level turns on
 // automatically when Infra publishes the registry of distributed stores in DI.
-cachedScoped(IProductService, ProductService, deps);
+scoped(IProductService, ProductService, deps);
 ```
 
 ---
@@ -620,32 +619,27 @@ class UserService implements IUserStore {
 
 ---
 
-## 10. DI providers: `cachedSingleton` / `cachedScoped` (+ auto-hook)
+## 10. DI registration: `singleton` / `scoped` with the cache hook
 
-One provider covers both levels. `@Cacheable` → the in-memory `ICache`; `@CacheableRedis` →
-the distributed `DISTRIBUTED_SERVICE_CACHE`, **automatically** if the registry is
-registered through Infra/DI. There are no separate `redisCached*` / `hybridCached*` anymore.
+`memory()` registers a hook on the core `singleton()` / `scoped()` providers: if a class
+carries `@Cacheable` / `@CacheableRedis`, the regular registration is wrapped with a
+caching proxy. One proxy routes `@Cacheable` to the in-memory `ICache` and
+`@CacheableRedis` to the distributed `DISTRIBUTED_SERVICE_CACHE`. The former
+`cachedSingleton` / `cachedScoped` helpers were removed in 0.98.34: they did the same.
 
-| Provider | Decorators | DI dependencies | Scope |
-| --- | --- | --- | --- |
-| `cachedSingleton` | `@Cacheable` and/or `@CacheableRedis` | `ICache`, `CACHE_POLICIES`, (optional) `DISTRIBUTED_SERVICE_CACHE` | singleton |
-| `cachedScoped` | `@Cacheable` and/or `@CacheableRedis` | the same | scoped |
+The hook checks the lifetime at container build (0.98.34):
 
-Removed aliases: `src/bazis/core/cache/COMPATIBILITY.md`.
+| Lifetime | Rule |
+| --- | --- |
+| `singleton` | Any declaration; the automatic key works across calls |
+| `scoped` | Every cached method needs an explicit `key` (or a named `policy`): the automatic key belongs to the instance, so it would cache within one request only. Otherwise `CacheDeclarationError` at startup |
+| `transient` | Refused with `CacheDeclarationError`: a new instance per injection never reuses its cache |
 
 ```ts
 // Interface token ← proxy ← implementation class with decorators.
-// Works for both @Cacheable and @CacheableRedis (if the backend is configured).
-cachedScoped(IUserStore, UserService, [repositoryFor(User)]);
+scoped(IUserStore, UserService);
 ```
 
-### 10.0. Out of the box (auto-hook)
-
-`memory()` registers a hook on the core `singleton()` / `scoped()` providers: if a class
-carries `@Cacheable` / `@CacheableRedis`, the regular registration is **automatically**
-wrapped with a caching proxy. An explicit `cachedScoped` is needed only when you want to
-be completely explicit.
-
 ### 10.1. Interface vs implementation: a common question
 
 ```ts
@@ -659,7 +653,7 @@ class UserService implements IUserStore {
 }
 
 // ✅ correct
-cachedScoped(IUserStore, UserService, deps);
+scoped(IUserStore, UserService, deps);
 
 // ❌ a decorator on an interface does not work
 // With memory() connected, a plain singleton(IUserStore, UserService)
@@ -674,7 +668,7 @@ or a root import of `memory()`. A feature module registers only its own service:
 ```ts
 @Module({
   imports: [UsersDataModule],
-  providers: [cachedScoped(IUserStore, UserService, deps)],
+  providers: [scoped(IUserStore, UserService, deps)],
 })
 class UsersModule {}
 ```
@@ -1066,7 +1060,7 @@ class UserService implements IUserStore {
 
 // UsersModule:
 imports: [UsersDataModule],
-providers: [cachedScoped(IUserStore, UserService, deps)],
+providers: [scoped(IUserStore, UserService, deps)],
 ```
 
 `@CacheableRedis.findByName` uses the distributed level automatically when the backend is
@@ -1174,7 +1168,7 @@ Checklist:
 
 1. The decorator is on the **class `UserService`**, not on `interface IUserStore`.
 2. The root app installs `cache: memory()` or imports `memory()` (auto-hook + `ICache`, `CACHE_POLICIES`).
-3. The registration goes through `singleton`/`scoped` (the auto-hook wraps it) or explicitly `cachedScoped`/`cachedSingleton`.
+3. The registration goes through `singleton`/`scoped` (the cache hook wraps it); a scoped one needs an explicit `key`.
 4. The options have **`seconds`** (inline or in the `policy`).
 5. For `@CacheableRedis`, infra connects `redisConnect(redisConfig, { cache: "distributed" })`, otherwise the call throws.
 
@@ -1190,7 +1184,7 @@ Checklist:
 async byId(id: number) { ... }
 
 // UsersModule.ts: registration on the interface token
-cachedScoped(IUserStore, UserService, deps);
+scoped(IUserStore, UserService, deps);
 ```
 
 The controller gets the proxy registered as `IUserStore`. The metadata is read from the `UserService` class (`Symbol.metadata`), not from the interface.
@@ -1242,28 +1236,16 @@ Technically yes, but **do not**: a startup warning, and Redis wins. Pick one sto
 
 ### Can `@Cacheable` and `@CacheableRedis` be on one method?
 
-**No**: a runtime error. On **different** methods of one class use a regular `cachedScoped` (one proxy routes memory and distributed).
+**No**: a runtime error. On **different** methods of one class use a regular `scoped` registration (one proxy routes memory and distributed).
 
 ---
 
-### `cachedSingleton` or `cachedScoped`?
-
-| | singleton | scoped |
-| --- | --- | --- |
-| Proxy instance | one per DI registration in the container | one per DI registration in the scope |
-| `@Cacheable` cache | the shared ICache store, automatic keys are isolated per instance | the same ICache store, automatic keys are isolated per instance |
-| ORM `DbContext` | ⚠️ careful | ✅ the typical case |
-
-A `UserService` with an ORM → **`cachedScoped`**. A stateless read-only service without scoped deps → `cachedSingleton` is fine.
-An explicit `key` in `cachedScoped` and `cachedSingleton` is a sharing contract: include the
-tenant/user in it if the result is personalized. Without an explicit `key` the framework
-isolates the automatic key per instance, so hidden constructor state does not leak into the
-response of another registration or request. This also applies to `@CacheableRedis`:
-sharing between processes and reuse after a restart need an explicit application `key`.
-DI creates the object with a regular class provider and then applies the proxy;
-constructor deps and lifecycle are not bypassed.
+### `singleton` or `scoped`?
 
----
+A `UserService` with an ORM is **`scoped`**: give every cached method an explicit `key`
+that includes the user or tenant when the result depends on them. A stateless read-only
+service without scoped dependencies can be a `singleton`; its automatic keys work across
+calls.
 
 ### Is Redis needed for the application to work?
 

package/core/cache/decorators/Cacheable.ts

@@ -12,8 +12,9 @@ type ClassOrMethodDecorator = (
  * Caches the return value of a service/provider method in {@link ICache}.
  *
  * Mirrors Spring / FusionCache `@Cacheable`. Put the decorator on the
- * **implementation class**, then register via {@link cachedSingleton} or
- * {@link cachedScoped} so DI returns a caching proxy for the interface token.
+ * **implementation class** and register it as usual (`scoped`, `singleton`):
+ * with the cache module installed, DI returns a caching proxy. A scoped
+ * service needs an explicit `key`; a transient one cannot cache.
  *
  * ```ts
  * class UserService implements IUserStore {
@@ -21,7 +22,7 @@ type ClassOrMethodDecorator = (
  *   async byId(id: number) { ... }
  * }
  *
- * cachedScoped(IUserStore, UserService, [repositoryFor(User)])
+ * scoped(IUserStore, UserService)
  * ```
  */
 export function Cacheable(options: CacheableOptions): ClassOrMethodDecorator {

package/core/cache/decorators/CacheableRedis.ts

@@ -12,9 +12,8 @@ type ClassOrMethodDecorator = (
  * Shared service method cache backed by the distributed tier (multi-instance safe).
  *
  * Requires a distributed backend: add `redisConnect(redisConfig, { cache: "distributed" })`
- * to your `@Infra` manifest. Register the class with the usual `cachedScoped` /
- * `cachedSingleton` (or just `scoped` / `singleton` — the auto-hook wraps it). The distributed
- * tier activates automatically when a backend is configured.
+ * to your `@Infra` manifest. Register the class as usual (`scoped` / `singleton`):
+ * the cache module wraps it. Values must be plain JSON.
  *
  * ```ts
  * class UserService implements IUserStore {
@@ -22,7 +21,7 @@ type ClassOrMethodDecorator = (
  *   async byId(id: number) { ... }
  * }
  *
- * cachedScoped(IUserStore, UserService, [repositoryFor(User)]);
+ * scoped(IUserStore, UserService);
  * ```
  */
 export function CacheableRedis(options: CacheableRedisOptions): ClassOrMethodDecorator {

package/core/cache/di/classProviderHook.ts

@@ -1,4 +1,5 @@
 import type { Class, ClassProviderHook, Token } from "../../di";
+import { CacheDeclarationError } from "../errors/CacheError";
 import { cacheableMetaOf, hasCacheableMethods } from "../decorators/cacheableMetadata";
 import { cacheableRedisMetaOf, hasCacheableRedisMethods } from "../decorators/cacheableRedisMetadata";
 import { cachedScoped, cachedSingleton } from "../providers/cachedProviders";
@@ -16,6 +17,7 @@ export const cacheableClassProviderHook: ClassProviderHook = ({ lifetime, provid
   }
   const token = provide as Token<object>;
   const impl = useClass as Class<object>;
+  assertCacheableLifetime(impl, lifetime);
   if (lifetime === "scoped") {
     return cachedScoped(token, impl, deps);
   }
@@ -24,3 +26,32 @@ export const cacheableClassProviderHook: ClassProviderHook = ({ lifetime, provid
   }
   return undefined;
 };
+
+interface Declared { readonly key?: unknown; readonly policy?: unknown }
+
+/**
+ * A cache that can never hit is refused at startup, as an invalid registration
+ * (a DI error: the start prints it as a configuration error). The automatic key belongs
+ * to the service instance (a scoped result may depend on the request's user),
+ * so without an explicit `key` a scoped service caches only within one request,
+ * and a transient one — never.
+ */
+function assertCacheableLifetime(impl: Class<object>, lifetime: string): void {
+  const declarations: { decorator: string; classLevel?: Declared; methods: ReadonlyMap<string | symbol, Declared> }[] = [];
+  const memory = cacheableMetaOf(impl);
+  if (hasCacheableMethods(memory)) declarations.push({ decorator: "@Cacheable", classLevel: memory!.cacheable, methods: memory!.methods });
+  const shared = cacheableRedisMetaOf(impl);
+  if (hasCacheableRedisMethods(shared)) declarations.push({ decorator: "@CacheableRedis", classLevel: shared!.cacheableRedis, methods: shared!.methods });
+  for (const { decorator, classLevel, methods } of declarations) {
+    if (lifetime === "transient") {
+      throw new CacheDeclarationError(`${impl.name} uses ${decorator} but is registered transient: a new instance for every injection never reuses its cache. Register it as singleton or scoped.`);
+    }
+    if (lifetime !== "scoped") continue;
+    const names = methods.size > 0 ? [...methods.keys()] : ["(every method)"];
+    for (const name of names) {
+      const declared = { ...classLevel, ...(typeof name === "string" && name === "(every method)" ? {} : methods.get(name)) };
+      if (declared.key !== undefined || declared.policy !== undefined) continue;
+      throw new CacheDeclarationError(`${impl.name}.${String(name)}: ${decorator} without key on a scoped service caches only within one request (the automatic key belongs to the instance). Set key — include the user or tenant when the result depends on them — or register ${impl.name} as a singleton.`);
+    }
+  }
+}

package/core/cache/distributed/DistributedCache.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { CacheValueError } from "../errors/CacheError";
+import { CacheUnavailableError, CacheValueError } from "../errors/CacheError";
 import { assertCacheKey, measureStringBytes } from "../internal/CacheKeyGuard";
 import type { CacheCodec } from "./CacheCodec";
 import type {
@@ -36,8 +36,12 @@ export interface DistributedCacheConfig {
   readonly maxValueBytes?: number;
   /** Poll interval (ms) while waiting for a peer worker to fill the cache. */
   readonly pollIntervalMs?: number;
+  /** Bound of one store operation (ms); a hung store must not hang the caller. Default 1000. */
+  readonly operationTimeoutMs?: number;
 }
 
+const DEFAULT_OPERATION_TIMEOUT_MS = 1000;
+
 /**
  * Backend-agnostic distributed cache. Owns all caching policy and delegates raw
  * I/O to a {@link DistributedCacheDriver}. One instance per (connection × namespace).
@@ -52,6 +56,9 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
   private readonly fullPrefix: string;
   private readonly maxKeyLength: number;
   private readonly pollIntervalMs: number;
+  private readonly operationTimeoutMs: number;
+  /** The driver with every operation bounded by {@link io}. */
+  private readonly ioCall: DistributedCacheDriver;
 
   public readonly connectionName: string;
   public readonly keyPrefix: string;
@@ -71,6 +78,9 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
     if (snapshot.maxValueBytes !== undefined && (!Number.isInteger(snapshot.maxValueBytes) || snapshot.maxValueBytes <= 0)) {
       throw new CacheValueError("maxValueBytes must be a positive integer");
     }
+    if (snapshot.operationTimeoutMs !== undefined && (!Number.isSafeInteger(snapshot.operationTimeoutMs) || snapshot.operationTimeoutMs <= 0 || snapshot.operationTimeoutMs > 2_147_483_647)) {
+      throw new CacheValueError("operationTimeoutMs must be a positive integer of milliseconds");
+    }
     if (snapshot.pollIntervalMs !== undefined && (!Number.isFinite(snapshot.pollIntervalMs) || snapshot.pollIntervalMs <= 0)) {
       throw new CacheValueError("pollIntervalMs must be a positive number");
     }
@@ -80,12 +90,40 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
     this.fullPrefix = `${snapshot.keyPrefix}${snapshot.namespace ?? ""}`;
     this.maxKeyLength = snapshot.maxKeyLength ?? DEFAULT_DISTRIBUTED_MAX_KEY_LENGTH;
     this.pollIntervalMs = snapshot.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    this.operationTimeoutMs = snapshot.operationTimeoutMs ?? DEFAULT_OPERATION_TIMEOUT_MS;
+    this.ioCall = new Proxy(driver, {
+      get: (target, property) => {
+        const member = (target as unknown as Record<PropertyKey, unknown>)[property];
+        return typeof member === "function"
+          ? (...args: unknown[]) => this.io(() => (member as (...values: unknown[]) => Promise<unknown>).apply(target, args))
+          : member;
+      },
+    });
+  }
+
+  /**
+   * One store operation, bounded by `operationTimeoutMs`. A timeout or a driver
+   * failure becomes {@link CacheUnavailableError}; the native operation is not
+   * cancelled (the driver has no cancellation), only no longer awaited.
+   */
+  private io<T>(work: () => Promise<T>): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new CacheUnavailableError(
+        `Distributed cache "${this.connectionName}" did not answer within ${this.operationTimeoutMs} ms.`,
+      )), this.operationTimeoutMs);
+      let started: Promise<T>;
+      try { started = work(); } catch (error) { clearTimeout(timer); reject(unavailable(this.connectionName, error)); return; }
+      started.then(
+        (value) => { clearTimeout(timer); resolve(value); },
+        (error: unknown) => { clearTimeout(timer); reject(unavailable(this.connectionName, error)); },
+      );
+    });
   }
 
   public async get<T = TValue>(key: string): Promise<T | undefined> {
     assertCacheKey(key, this.maxKeyLength);
     const storageKey = this.storageKey(key);
-    const raw = await this.driver.read(storageKey);
+    const raw = await this.ioCall.read(storageKey);
     if (raw === null) {
       return undefined;
     }
@@ -93,7 +131,7 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
       return this.codec.deserialize(decodeEnvelope(raw).payload) as unknown as T;
     } catch {
       try {
-        await this.driver.deleteIfValue(storageKey, raw);
+        await this.ioCall.deleteIfValue(storageKey, raw);
       } catch {
         // A corrupt cache entry is still a miss when backend cleanup fails.
         // Do not turn best-effort cache maintenance into a request failure.
@@ -108,7 +146,14 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
     options: DistributedCacheSetOptions,
   ): Promise<T | undefined> {
     const normalizedOptions = this.normalizeSetOptions(options);
-    const hit = await this.get<T>(key);
+    let hit: T | undefined;
+    try {
+      hit = await this.get<T>(key);
+    } catch (error) {
+      // The cache is optional: an unavailable store means "compute it now".
+      if (error instanceof CacheUnavailableError) return factory();
+      throw error;
+    }
     if (hit !== undefined) {
       return hit;
     }
@@ -132,7 +177,7 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
   public async remove(key: string): Promise<boolean> {
     assertCacheKey(key, this.maxKeyLength);
     this.inFlight.delete(key);
-    return this.driver.invalidate(this.entryVersionKey(key), this.storageKey(key), this.lockKeyFor(key));
+    return this.ioCall.invalidate(this.entryVersionKey(key), this.storageKey(key), this.lockKeyFor(key));
   }
 
   public async evictByTag(tag: string): Promise<number> {
@@ -142,8 +187,8 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
     }
     const versionKey = this.tagVersionKey(tag);
     const pendingKey = this.tagPendingKey(tag);
-    await this.driver.advanceTagGeneration(versionKey, pendingKey);
-    const generations = [...await this.driver.tagMembers(pendingKey)]
+    await this.ioCall.advanceTagGeneration(versionKey, pendingKey);
+    const generations = [...await this.ioCall.tagMembers(pendingKey)]
       .filter((value) => /^\d+$/.test(value))
       .sort((left, right) => Number(left) - Number(right));
     let removed = 0;
@@ -155,7 +200,7 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
 
   private async evictTagGeneration(tag: string, generation: string, pendingKey: string): Promise<number> {
     const tagKey = this.tagKey(tag, generation);
-    const members = await this.driver.tagMembers(tagKey);
+    const members = await this.ioCall.tagMembers(tagKey);
     let removed = 0;
     for (const member of members) {
       const parsed = decodeTagMember(member);
@@ -165,19 +210,19 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
       if (!parsed.storageKey.startsWith(`${this.fullPrefix}entry:`)) {
         continue;
       }
-      const raw = await this.driver.read(parsed.storageKey);
+      const raw = await this.ioCall.read(parsed.storageKey);
       if (raw === null) {
         continue;
       }
       if (decodeEnvelope(raw).token !== parsed.token) {
         continue;
       }
-      if (await this.driver.deleteIfValue(parsed.storageKey, raw)) {
+      if (await this.ioCall.deleteIfValue(parsed.storageKey, raw)) {
         removed += 1;
       }
     }
-    await this.driver.delete([tagKey]);
-    await this.driver.removeTagMembers(pendingKey, [generation]);
+    await this.ioCall.delete([tagKey]);
+    await this.ioCall.removeTagMembers(pendingKey, [generation]);
     return removed;
   }
 
@@ -215,9 +260,21 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
     const lockTtl = Math.max(1, Math.floor(options.lockSeconds ?? this.config.defaultLockSeconds));
     const token = randomUUID();
 
-    const acquired = await this.driver.acquireLock(lockKey, token, lockTtl);
+    let acquired: boolean;
+    try {
+      acquired = await this.ioCall.acquireLock(lockKey, token, lockTtl);
+    } catch (error) {
+      if (error instanceof CacheUnavailableError) return factory();
+      throw error;
+    }
     if (!acquired) {
-      const peerValue = await this.waitForPeerResult<T>(key, lockKey, lockTtl);
+      let peerValue: T | undefined;
+      try {
+        peerValue = await this.waitForPeerResult<T>(key, lockKey, lockTtl);
+      } catch (error) {
+        if (error instanceof CacheUnavailableError) return factory();
+        throw error;
+      }
       if (peerValue !== undefined) return peerValue;
       if (contentionAttempt < 2) {
         return this.runLockedFactory(key, factory, options, contentionAttempt + 1);
@@ -228,11 +285,18 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
     }
 
     try {
-      const again = await this.get<T>(key);
-      if (again !== undefined) {
-        return again;
+      let versionChecks: readonly DistributedCacheVersionCheck[];
+      try {
+        const again = await this.get<T>(key);
+        if (again !== undefined) {
+          return again;
+        }
+        versionChecks = await this.captureVersions(key, options.tags);
+      } catch (error) {
+        // The store went away under the lock: compute, but do not write.
+        if (error instanceof CacheUnavailableError) return await factory();
+        throw error;
       }
-      const versionChecks = await this.captureVersions(key, options.tags);
       const value = await factory();
       if (value !== undefined) {
         await this.trySet(key, value, options, lockKey, token, versionChecks);
@@ -243,7 +307,7 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
         // Unlock is best effort: a transport error must not replace a fresh
         // service result or the factory's original exception. The lock still
         // has a bounded TTL, so another worker eventually makes progress.
-        await this.driver.releaseLock(lockKey, token, this.entryVersionKey(key));
+        await this.ioCall.releaseLock(lockKey, token, this.entryVersionKey(key));
       } catch {
         // Intentionally preserve the primary outcome.
       }
@@ -257,7 +321,7 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
       if (hit !== undefined) {
         return hit;
       }
-      if (await this.driver.read(lockKey) === null) {
+      if (await this.ioCall.read(lockKey) === null) {
         break;
       }
       await Bun.sleep(this.pollIntervalMs);
@@ -273,8 +337,11 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
     lockToken: string,
     versionChecks: readonly DistributedCacheVersionCheck[],
   ): Promise<void> {
+    // A value the codec refuses is a bug of the cached method, not a store
+    // outage: it surfaces instead of silently never being cached.
+    const serialized = this.codec.serialize(value as unknown as TValue);
     try {
-      await this.write(key, value as unknown as TValue, options, lockKey, lockToken, versionChecks);
+      await this.write(key, serialized, options, lockKey, lockToken, versionChecks);
     } catch {
       // Graceful degradation — the caller still receives the fresh value.
     }
@@ -282,14 +349,13 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
 
   private async write(
     key: string,
-    value: TValue,
+    serialized: string,
     options: DistributedCacheSetOptions,
     lockKey: string,
     lockToken: string,
     versionChecks: readonly DistributedCacheVersionCheck[],
   ): Promise<void> {
     assertCacheKey(key, this.maxKeyLength);
-    const serialized = this.codec.serialize(value);
 
     if (this.config.maxValueBytes !== undefined) {
       const bytes = measureStringBytes(serialized);
@@ -318,7 +384,7 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
       tags[index] = { key: tag.key, member: encodeTagMember(storageKey, writeToken) };
     }
     const envelope = encodeEnvelope(writeToken, serialized);
-    await this.driver.writeIfLockOwner({
+    await this.ioCall.writeIfLockOwner({
       lockKey,
       lockToken,
       key: storageKey,
@@ -336,7 +402,7 @@ export class DistributedCache<TValue = unknown> implements IDistributedCache<TVa
     const keys = [this.entryVersionKey(key), ...(tags ?? []).map((tag) => this.tagVersionKey(tag))];
     return Promise.all(keys.map(async (versionKey) => ({
       key: versionKey,
-      expected: await this.driver.read(versionKey),
+      expected: await this.ioCall.read(versionKey),
     })));
   }
 
@@ -401,3 +467,8 @@ function decodeTagMember(member: string): { readonly storageKey: string; readonl
   }
   return undefined;
 }
+
+function unavailable(connection: string, error: unknown): CacheUnavailableError {
+  if (error instanceof CacheUnavailableError) return error;
+  return new CacheUnavailableError(`Distributed cache "${connection}" failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+}

package/core/cache/distributed/IDistributedCache.ts

@@ -1,3 +1,4 @@
+import { createToken, type InjectionToken } from "../../di";
 import type { CacheSetOptions } from "../types/CacheOptions";
 
 /** Default named connection used when a decorator omits `connection`. */
@@ -38,3 +39,11 @@ export interface IDistributedCache<TValue = unknown> {
   /** Removes all entries carrying `tag`; returns the number removed. */
   evictByTag(tag: string): Promise<number>;
 }
+
+/**
+ * The distributed cache by type: `constructor(private readonly shared: IDistributedCache)`.
+ * Registered by `redisConnect(config, { cache: "distributed" })` for its one
+ * connection; a custom backend with several connections keeps
+ * `DISTRIBUTED_SERVICE_CACHE.resolve(name)`.
+ */
+export const IDistributedCache = createToken<IDistributedCache>("IDistributedCache") as InjectionToken<IDistributedCache<unknown>>;

package/core/cache/distributed/codecs.ts

@@ -1,12 +1,59 @@
 import type { CachedHttpPayload } from "../http/CachedHttpPayload";
 import type { CacheCodec } from "./CacheCodec";
+import { CacheValueError } from "../errors/CacheError";
 
-/** JSON codec for arbitrary service values (`@Cacheable` distributed tier). */
+/**
+ * JSON codec for service values (`@CacheableRedis`, `IDistributedCache`). It
+ * refuses a value that JSON would change on the way back — a Date comes back
+ * as a string, a Set or Map as `{}` — instead of returning altered data on a
+ * cache hit.
+ */
 export const jsonCacheCodec: CacheCodec<unknown> = {
-  serialize: (value) => JSON.stringify(value),
+  serialize: (value) => {
+    const problem = notPlainJson(value, "value", new Set());
+    if (problem !== undefined) {
+      throw new CacheValueError(`Cache value is not plain JSON: ${problem}. Return plain data (an ISO string for a date, an array for a set), or cache it in memory with @Cacheable.`);
+    }
+    return JSON.stringify(value);
+  },
   deserialize: (raw) => JSON.parse(raw) as unknown,
 };
 
+/** Where `value` stops surviving JSON unchanged, or undefined when it does. */
+function notPlainJson(value: unknown, path: string, seen: Set<object>): string | undefined {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return undefined;
+  if (typeof value === "number") return Number.isFinite(value) ? undefined : `${path} is ${String(value)} (JSON writes null)`;
+  if (typeof value === "bigint") return `${path} is a bigint`;
+  if (typeof value !== "object") return `${path} is a ${typeof value}`;
+  if (seen.has(value)) return `${path} is a circular reference`;
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      for (let index = 0; index < value.length; index += 1) {
+        const item: unknown = value[index];
+        if (item === undefined) return `${path}[${index}] is undefined (JSON writes null)`;
+        const problem = notPlainJson(item, `${path}[${index}]`, seen);
+        if (problem !== undefined) return problem;
+      }
+      return undefined;
+    }
+    const prototype = Object.getPrototypeOf(value) as object | null;
+    if (prototype !== Object.prototype && prototype !== null) {
+      const name = (value as { constructor?: { name?: string } }).constructor?.name || "object with a prototype";
+      return `${path} is a ${name}${value instanceof Date ? " (JSON returns a string)" : value instanceof Map || value instanceof Set ? " (JSON returns {})" : ""}`;
+    }
+    for (const key of Object.keys(value)) {
+      const item = (value as Record<string, unknown>)[key];
+      if (item === undefined) continue;                 // dropped and read back as undefined
+      const problem = notPlainJson(item, `${path}.${key}`, seen);
+      if (problem !== undefined) return problem;
+    }
+    return undefined;
+  } finally {
+    seen.delete(value);
+  }
+}
+
 interface SerializedHttpPayload {
   readonly status: number;
   readonly headers: Readonly<Record<string, string>>;

package/core/cache/distributed/index.ts

@@ -3,7 +3,7 @@ export { jsonCacheCodec, httpPayloadCacheCodec } from "./codecs";
 export {
   DEFAULT_CACHE_CONNECTION,
   type DistributedCacheSetOptions,
-  type IDistributedCache,
+  IDistributedCache,
 } from "./IDistributedCache";
 export type {
   DistributedCacheDriver,