@bymax-one/nest-cache 1.2.2 → 1.2.4

package/dist/admin/index.d.cts

@@ -132,6 +132,9 @@ declare class BymaxCacheAdminModule {
 }
 
 /** Administration options after defaults are merged and validated. */
+/**
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
+ */
 interface ResolvedAdminOptions {
     readonly scopes: readonly CacheScope[];
     readonly degradedAboveMs: number;
@@ -150,6 +153,8 @@ interface ResolvedAdminOptions {
  * @returns The frozen resolved options.
  * @throws {CacheException} `INVALID_SCOPE` when a scope is malformed or a
  *   threshold is not a positive integer.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function resolveAdminOptions(options: BymaxCacheAdminModuleOptions): Readonly<ResolvedAdminOptions>;
 
@@ -370,6 +375,8 @@ interface RedisStats {
  * 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.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 type ICacheProbe = Pick<CacheService, 'ping' | 'info'>;
 /** Reports whether the cache is answering, what it is doing, and how it is wired. */
@@ -432,8 +439,14 @@ declare class CacheStatusService {
  * this subpath.
  */
 /** One entry of a pipeline's result: an error, or a value. */
+/**
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
+ */
 type PipelineReply = [Error | null, unknown];
 /** A pipeline being composed, chainable the way ioredis's commander is. */
+/**
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
+ */
 interface IRedisPipeline {
     /** Queues `TYPE`. */
     type(key: string): IRedisPipeline;
@@ -445,6 +458,9 @@ interface IRedisPipeline {
     exec(): Promise<PipelineReply[] | null>;
 }
 /** The subset of the Redis client this surface reads through. */
+/**
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
+ */
 interface IRedisReader {
     /** Cursor-based key iteration. */
     scan(cursor: string | number, matchToken: 'MATCH', pattern: string, countToken: 'COUNT', count: number | string): Promise<[string, string[]]>;
@@ -478,6 +494,9 @@ interface IRedisReader {
     call(command: string, ...args: (string | number)[]): Promise<unknown>;
 }
 /** How the administration surface obtains its reader. */
+/**
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
+ */
 interface IRedisReaderSource {
     /**
      * Returns the client.
@@ -770,6 +789,8 @@ declare class CacheAdminService {
  *
  * @param pattern - A pattern that already satisfies {@link SCOPE_PATTERN_SHAPE}.
  * @returns The literal prefix, and whether a trailing `*` allows a suffix.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function readScopePattern(pattern: string): {
     readonly prefix: string;
@@ -784,6 +805,8 @@ declare function readScopePattern(pattern: string): {
  * @param pattern - The scope's validated match pattern.
  * @param key - The key a caller named.
  * @returns `true` when the key belongs to the scope.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function isKeyInScope(pattern: string, key: string): boolean;
 /**
@@ -799,6 +822,8 @@ declare function isKeyInScope(pattern: string, key: string): boolean;
  * @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.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function validateScopes(scopes: readonly CacheScope[]): readonly CacheScope[];
 /**
@@ -811,6 +836,8 @@ declare function validateScopes(scopes: readonly CacheScope[]): readonly CacheSc
  * @param id - The identifier from the request.
  * @returns The scope.
  * @throws {CacheException} `SCOPE_NOT_FOUND` when no declaration has that id.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function findScope(scopes: readonly CacheScope[], id: string): CacheScope;
 
@@ -842,6 +869,8 @@ declare function findScope(scopes: readonly CacheScope[], id: string): CacheScop
  *
  * @param text - The raw `INFO` output.
  * @returns Field name to raw text value.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function parseInfoFields(text: string): ReadonlyMap<string, string>;
 /**
@@ -850,6 +879,8 @@ declare function parseInfoFields(text: string): ReadonlyMap<string, string>;
  * @param infoText - The raw `INFO` output.
  * @param readAt - When the reading was taken, by the reading host's clock.
  * @returns The parsed statistics.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function readRedisStats(infoText: string, readAt: Date): RedisStats;
 
@@ -867,6 +898,8 @@ declare function readRedisStats(infoText: string, readAt: Date): RedisStats;
  *
  * @param reply - Whatever the server answered.
  * @returns The recognised type, or `other`.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function readKeyType(reply: unknown): RedisKeyType;
 /**
@@ -878,6 +911,8 @@ declare function readKeyType(reply: unknown): RedisKeyType;
  *
  * @param reply - Whatever the server answered.
  * @returns Whether the key expires, is persistent, or is gone.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function readKeyTtl(reply: unknown): KeyTtl;
 /**
@@ -889,6 +924,8 @@ declare function readKeyTtl(reply: unknown): KeyTtl;
  *
  * @param reply - Whatever the server answered.
  * @returns The size in bytes, or `null` when no size was reported.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function readSizeBytes(reply: unknown): number | null;
 

package/dist/admin/index.d.ts

@@ -132,6 +132,9 @@ declare class BymaxCacheAdminModule {
 }
 
 /** Administration options after defaults are merged and validated. */
+/**
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
+ */
 interface ResolvedAdminOptions {
     readonly scopes: readonly CacheScope[];
     readonly degradedAboveMs: number;
@@ -150,6 +153,8 @@ interface ResolvedAdminOptions {
  * @returns The frozen resolved options.
  * @throws {CacheException} `INVALID_SCOPE` when a scope is malformed or a
  *   threshold is not a positive integer.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function resolveAdminOptions(options: BymaxCacheAdminModuleOptions): Readonly<ResolvedAdminOptions>;
 
@@ -370,6 +375,8 @@ interface RedisStats {
  * 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.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 type ICacheProbe = Pick<CacheService, 'ping' | 'info'>;
 /** Reports whether the cache is answering, what it is doing, and how it is wired. */
@@ -432,8 +439,14 @@ declare class CacheStatusService {
  * this subpath.
  */
 /** One entry of a pipeline's result: an error, or a value. */
+/**
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
+ */
 type PipelineReply = [Error | null, unknown];
 /** A pipeline being composed, chainable the way ioredis's commander is. */
+/**
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
+ */
 interface IRedisPipeline {
     /** Queues `TYPE`. */
     type(key: string): IRedisPipeline;
@@ -445,6 +458,9 @@ interface IRedisPipeline {
     exec(): Promise<PipelineReply[] | null>;
 }
 /** The subset of the Redis client this surface reads through. */
+/**
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
+ */
 interface IRedisReader {
     /** Cursor-based key iteration. */
     scan(cursor: string | number, matchToken: 'MATCH', pattern: string, countToken: 'COUNT', count: number | string): Promise<[string, string[]]>;
@@ -478,6 +494,9 @@ interface IRedisReader {
     call(command: string, ...args: (string | number)[]): Promise<unknown>;
 }
 /** How the administration surface obtains its reader. */
+/**
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
+ */
 interface IRedisReaderSource {
     /**
      * Returns the client.
@@ -770,6 +789,8 @@ declare class CacheAdminService {
  *
  * @param pattern - A pattern that already satisfies {@link SCOPE_PATTERN_SHAPE}.
  * @returns The literal prefix, and whether a trailing `*` allows a suffix.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function readScopePattern(pattern: string): {
     readonly prefix: string;
@@ -784,6 +805,8 @@ declare function readScopePattern(pattern: string): {
  * @param pattern - The scope's validated match pattern.
  * @param key - The key a caller named.
  * @returns `true` when the key belongs to the scope.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function isKeyInScope(pattern: string, key: string): boolean;
 /**
@@ -799,6 +822,8 @@ declare function isKeyInScope(pattern: string, key: string): boolean;
  * @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.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function validateScopes(scopes: readonly CacheScope[]): readonly CacheScope[];
 /**
@@ -811,6 +836,8 @@ declare function validateScopes(scopes: readonly CacheScope[]): readonly CacheSc
  * @param id - The identifier from the request.
  * @returns The scope.
  * @throws {CacheException} `SCOPE_NOT_FOUND` when no declaration has that id.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function findScope(scopes: readonly CacheScope[], id: string): CacheScope;
 
@@ -842,6 +869,8 @@ declare function findScope(scopes: readonly CacheScope[], id: string): CacheScop
  *
  * @param text - The raw `INFO` output.
  * @returns Field name to raw text value.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function parseInfoFields(text: string): ReadonlyMap<string, string>;
 /**
@@ -850,6 +879,8 @@ declare function parseInfoFields(text: string): ReadonlyMap<string, string>;
  * @param infoText - The raw `INFO` output.
  * @param readAt - When the reading was taken, by the reading host's clock.
  * @returns The parsed statistics.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function readRedisStats(infoText: string, readAt: Date): RedisStats;
 
@@ -867,6 +898,8 @@ declare function readRedisStats(infoText: string, readAt: Date): RedisStats;
  *
  * @param reply - Whatever the server answered.
  * @returns The recognised type, or `other`.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function readKeyType(reply: unknown): RedisKeyType;
 /**
@@ -878,6 +911,8 @@ declare function readKeyType(reply: unknown): RedisKeyType;
  *
  * @param reply - Whatever the server answered.
  * @returns Whether the key expires, is persistent, or is gone.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function readKeyTtl(reply: unknown): KeyTtl;
 /**
@@ -889,6 +924,8 @@ declare function readKeyTtl(reply: unknown): KeyTtl;
  *
  * @param reply - Whatever the server answered.
  * @returns The size in bytes, or `null` when no size was reported.
+ *
+ * @deprecated Implementation helper; will leave the public surface in 2.0.0. Do not depend on it.
  */
 declare function readSizeBytes(reply: unknown): number | null;
 

package/dist/server/index.cjs

@@ -67,7 +67,8 @@ var CACHE_ERROR_CODES = {
   INVALID_SCOPE: "cache.invalid_scope",
   SCOPE_NOT_FOUND: "cache.scope_not_found",
   SCOPE_NOT_READABLE: "cache.scope_not_readable",
-  KEY_NOT_IN_SCOPE: "cache.key_not_in_scope"
+  KEY_NOT_IN_SCOPE: "cache.key_not_in_scope",
+  INVALID_TTL: "cache.invalid_ttl"
 };
 
 // src/server/errors/cache-error-codes.ts
@@ -108,12 +109,17 @@ var CACHE_ERROR_MESSAGES = /* @__PURE__ */ new Map([
   [
     CACHE_ERROR_CODES.KEY_NOT_IN_SCOPE,
     "That key does not belong to the named administration scope."
+  ],
+  [
+    CACHE_ERROR_CODES.INVALID_TTL,
+    "A TTL in seconds must be a safe integer, and at least 1 for a write that sets one."
   ]
 ]);
 var CACHE_ERROR_STATUS = /* @__PURE__ */ new Map([
   [CACHE_ERROR_CODES.COMMAND_TIMEOUT, common.HttpStatus.GATEWAY_TIMEOUT],
   [CACHE_ERROR_CODES.CONNECTION_LOST, common.HttpStatus.SERVICE_UNAVAILABLE],
   [CACHE_ERROR_CODES.INVALID_KEY, common.HttpStatus.BAD_REQUEST],
+  [CACHE_ERROR_CODES.INVALID_TTL, common.HttpStatus.BAD_REQUEST],
   [CACHE_ERROR_CODES.FLUSH_DISABLED_IN_PRODUCTION, common.HttpStatus.FORBIDDEN]
 ]);
 var CacheException = class extends common.HttpException {
@@ -711,7 +717,7 @@ exports.KeyBuilder = __decorateClass([
   common.Injectable(),
   __decorateParam(0, common.Inject(BYMAX_CACHE_OPTIONS))
 ], exports.KeyBuilder);
-var MAX_PREVIEW_LENGTH = 100;
+var DESERIALIZATION_ERROR = "stored value is not valid JSON";
 var extractErrorMessage = (err) => err instanceof Error ? err.message : String(err);
 exports.JsonSerializer = class JsonSerializer {
   /**
@@ -753,17 +759,17 @@ exports.JsonSerializer = class JsonSerializer {
    * @param raw - The JSON string to decode.
    * @returns The decoded value, typed as `T`.
    * @throws {CacheException} `DESERIALIZATION_FAILED` when `raw` is not valid
-   *   JSON. `details.preview` carries at most {@link MAX_PREVIEW_LENGTH}
-   *   characters of `raw` (truncated with an ellipsis) to aid debugging without
-   *   leaking a large payload that may contain PII.
+   *   JSON. `details` holds a fixed `error` text and the `length` of `raw`; no
+   *   part of the stored value is echoed, as it may carry PII or a credential
+   *   (CLAUDE.md §4).
    */
   deserialize(raw) {
     try {
       return JSON.parse(raw);
-    } catch (err) {
+    } catch {
       throw new CacheException(CACHE_ERROR_CODES.DESERIALIZATION_FAILED, {
-        error: extractErrorMessage(err),
-        preview: raw.length > MAX_PREVIEW_LENGTH ? `${raw.substring(0, MAX_PREVIEW_LENGTH)}...` : raw
+        error: DESERIALIZATION_ERROR,
+        length: raw.length
       });
     }
   }
@@ -779,6 +785,17 @@ var resolveSerializer = (options, injected) => (
   options.serializer ?? injected ?? new exports.JsonSerializer()
 );
 
+// src/server/utils/ttl.ts
+var MIN_WRITE_TTL_SECONDS = 1;
+function assertTtlSeconds(ttlSeconds, minimum) {
+  if (!Number.isSafeInteger(ttlSeconds)) {
+    throw new CacheException(CACHE_ERROR_CODES.INVALID_TTL, { reason: "not_a_safe_integer" });
+  }
+  if (minimum !== void 0 && ttlSeconds < minimum) {
+    throw new CacheException(CACHE_ERROR_CODES.INVALID_TTL, { reason: "below_minimum", minimum });
+  }
+}
+
 // src/server/services/cache.service.ts
 var PRODUCTION_ENV = "production";
 var SCAN_COUNT = 100;
@@ -839,14 +856,17 @@ exports.CacheService = class CacheService {
    * @param prefix - Entity-group prefix.
    * @param id - Entity id.
    * @param value - The value to store (passed through the serializer).
-   * @param ttlSeconds - Optional expiry in seconds; omit for no expiration.
+   * @param ttlSeconds - Optional expiry in seconds, a safe integer of at least 1; omit for
+   *   no expiration.
    * @returns Resolves once the write completes.
    * @throws {CacheException} `SERIALIZATION_FAILED` when `value` cannot be encoded.
+   * @throws {CacheException} `INVALID_TTL` when `ttlSeconds` is not a safe integer of at least 1.
    */
   async set(prefix, id, value, ttlSeconds) {
     const key = this.keyBuilder.build(prefix, id);
     const raw = this.serializer.serialize(value);
     if (ttlSeconds !== void 0) {
+      assertTtlSeconds(ttlSeconds, MIN_WRITE_TTL_SECONDS);
       await this.connection.getClient().set(key, raw, "EX", ttlSeconds);
     } else {
       await this.connection.getClient().set(key, raw);
@@ -858,12 +878,15 @@ exports.CacheService = class CacheService {
    * @param prefix - Entity-group prefix.
    * @param id - Entity id.
    * @param value - The raw string to store as-is.
-   * @param ttlSeconds - Optional expiry in seconds; omit for no expiration.
+   * @param ttlSeconds - Optional expiry in seconds, a safe integer of at least 1; omit for
+   *   no expiration.
    * @returns Resolves once the write completes.
+   * @throws {CacheException} `INVALID_TTL` when `ttlSeconds` is not a safe integer of at least 1.
    */
   async setRaw(prefix, id, value, ttlSeconds) {
     const key = this.keyBuilder.build(prefix, id);
     if (ttlSeconds !== void 0) {
+      assertTtlSeconds(ttlSeconds, MIN_WRITE_TTL_SECONDS);
       await this.connection.getClient().set(key, value, "EX", ttlSeconds);
     } else {
       await this.connection.getClient().set(key, value);
@@ -876,13 +899,16 @@ exports.CacheService = class CacheService {
    * @param prefix - Entity-group prefix.
    * @param id - Entity id.
    * @param value - The value to store (passed through the serializer).
-   * @param ttlSeconds - Optional expiry in seconds applied on the same atomic write.
+   * @param ttlSeconds - Optional expiry in seconds applied on the same atomic write, a safe
+   *   integer of at least 1.
    * @returns `true` when the value was stored, `false` when the key already existed.
    * @throws {CacheException} `SERIALIZATION_FAILED` when `value` cannot be encoded.
+   * @throws {CacheException} `INVALID_TTL` when `ttlSeconds` is not a safe integer of at least 1.
    */
   async setNx(prefix, id, value, ttlSeconds) {
     const key = this.keyBuilder.build(prefix, id);
     const raw = this.serializer.serialize(value);
+    if (ttlSeconds !== void 0) assertTtlSeconds(ttlSeconds, MIN_WRITE_TTL_SECONDS);
     const result = ttlSeconds !== void 0 ? await this.connection.getClient().set(key, raw, "EX", ttlSeconds, "NX") : await this.connection.getClient().set(key, raw, "NX");
     return result === "OK";
   }
@@ -954,10 +980,13 @@ exports.CacheService = class CacheService {
    *
    * @param prefix - Entity-group prefix.
    * @param id - Entity id.
-   * @param ttlSeconds - Expiry in seconds.
+   * @param ttlSeconds - Expiry in seconds, a safe integer. As in Redis, zero or a negative
+   *   value deletes the key.
    * @returns `true` when the timeout was set, `false` when the key does not exist.
+   * @throws {CacheException} `INVALID_TTL` when `ttlSeconds` is not a safe integer.
    */
   async expire(prefix, id, ttlSeconds) {
+    assertTtlSeconds(ttlSeconds, void 0);
     const result = await this.connection.getClient().expire(this.keyBuilder.build(prefix, id), ttlSeconds);
     return result === 1;
   }
@@ -1165,6 +1194,9 @@ exports.CacheService = class CacheService {
    * @param prefix - Entity-group prefix.
    * @param pattern - Glob pattern for the id segment, e.g. `'*'`.
    * @returns The matching fully-namespaced keys.
+   * @throws {CacheException} `UNSUPPORTED_IN_CLUSTER` when called in cluster mode:
+   *   `KEYS` carries no key, so the cluster client sends it to one sampled node and the
+   *   reply would cover only that node's share of the keyspace.
    * @example
    * ```ts
    * await cache.keys('users', '*') // ['app:users:u_1', 'app:users:u_2']
@@ -1172,7 +1204,11 @@ exports.CacheService = class CacheService {
    */
   async keys(prefix, pattern) {
     const fullPattern = this.keyBuilder.build(prefix, pattern);
-    return this.connection.getClient().keys(fullPattern);
+    const client = this.connection.getClient();
+    if (!isScannableClient(client)) {
+      throw new CacheException(CACHE_ERROR_CODES.UNSUPPORTED_IN_CLUSTER, { operation: "keys" });
+    }
+    return client.keys(fullPattern);
   }
   /**
    * Iterates keys matching a pattern under a prefix using a non-blocking cursor.

package/dist/server/index.d.cts

@@ -591,9 +591,11 @@ declare class CacheService {
      * @param prefix - Entity-group prefix.
      * @param id - Entity id.
      * @param value - The value to store (passed through the serializer).
-     * @param ttlSeconds - Optional expiry in seconds; omit for no expiration.
+     * @param ttlSeconds - Optional expiry in seconds, a safe integer of at least 1; omit for
+     *   no expiration.
      * @returns Resolves once the write completes.
      * @throws {CacheException} `SERIALIZATION_FAILED` when `value` cannot be encoded.
+     * @throws {CacheException} `INVALID_TTL` when `ttlSeconds` is not a safe integer of at least 1.
      */
     set<T>(prefix: string, id: string, value: T, ttlSeconds?: number): Promise<void>;
     /**
@@ -602,8 +604,10 @@ declare class CacheService {
      * @param prefix - Entity-group prefix.
      * @param id - Entity id.
      * @param value - The raw string to store as-is.
-     * @param ttlSeconds - Optional expiry in seconds; omit for no expiration.
+     * @param ttlSeconds - Optional expiry in seconds, a safe integer of at least 1; omit for
+     *   no expiration.
      * @returns Resolves once the write completes.
+     * @throws {CacheException} `INVALID_TTL` when `ttlSeconds` is not a safe integer of at least 1.
      */
     setRaw(prefix: string, id: string, value: string, ttlSeconds?: number): Promise<void>;
     /**
@@ -613,9 +617,11 @@ declare class CacheService {
      * @param prefix - Entity-group prefix.
      * @param id - Entity id.
      * @param value - The value to store (passed through the serializer).
-     * @param ttlSeconds - Optional expiry in seconds applied on the same atomic write.
+     * @param ttlSeconds - Optional expiry in seconds applied on the same atomic write, a safe
+     *   integer of at least 1.
      * @returns `true` when the value was stored, `false` when the key already existed.
      * @throws {CacheException} `SERIALIZATION_FAILED` when `value` cannot be encoded.
+     * @throws {CacheException} `INVALID_TTL` when `ttlSeconds` is not a safe integer of at least 1.
      */
     setNx<T>(prefix: string, id: string, value: T, ttlSeconds?: number): Promise<boolean>;
     /**
@@ -667,8 +673,10 @@ declare class CacheService {
      *
      * @param prefix - Entity-group prefix.
      * @param id - Entity id.
-     * @param ttlSeconds - Expiry in seconds.
+     * @param ttlSeconds - Expiry in seconds, a safe integer. As in Redis, zero or a negative
+     *   value deletes the key.
      * @returns `true` when the timeout was set, `false` when the key does not exist.
+     * @throws {CacheException} `INVALID_TTL` when `ttlSeconds` is not a safe integer.
      */
     expire(prefix: string, id: string, ttlSeconds: number): Promise<boolean>;
     /**
@@ -809,6 +817,9 @@ declare class CacheService {
      * @param prefix - Entity-group prefix.
      * @param pattern - Glob pattern for the id segment, e.g. `'*'`.
      * @returns The matching fully-namespaced keys.
+     * @throws {CacheException} `UNSUPPORTED_IN_CLUSTER` when called in cluster mode:
+     *   `KEYS` carries no key, so the cluster client sends it to one sampled node and the
+     *   reply would cover only that node's share of the keyspace.
      * @example
      * ```ts
      * await cache.keys('users', '*') // ['app:users:u_1', 'app:users:u_2']
@@ -971,9 +982,9 @@ declare class JsonSerializer implements ISerializer {
      * @param raw - The JSON string to decode.
      * @returns The decoded value, typed as `T`.
      * @throws {CacheException} `DESERIALIZATION_FAILED` when `raw` is not valid
-     *   JSON. `details.preview` carries at most {@link MAX_PREVIEW_LENGTH}
-     *   characters of `raw` (truncated with an ellipsis) to aid debugging without
-     *   leaking a large payload that may contain PII.
+     *   JSON. `details` holds a fixed `error` text and the `length` of `raw`; no
+     *   part of the stored value is echoed, as it may carry PII or a credential
+     *   (CLAUDE.md §4).
      */
     deserialize<T>(raw: string): T;
 }
@@ -1199,6 +1210,7 @@ declare const CACHE_ERROR_CODES: {
     readonly SCOPE_NOT_FOUND: "cache.scope_not_found";
     readonly SCOPE_NOT_READABLE: "cache.scope_not_readable";
     readonly KEY_NOT_IN_SCOPE: "cache.key_not_in_scope";
+    readonly INVALID_TTL: "cache.invalid_ttl";
 };
 /** Union of every cache error code string value. */
 type CacheErrorCode = (typeof CACHE_ERROR_CODES)[keyof typeof CACHE_ERROR_CODES];

package/dist/server/index.d.ts

@@ -591,9 +591,11 @@ declare class CacheService {
      * @param prefix - Entity-group prefix.
      * @param id - Entity id.
      * @param value - The value to store (passed through the serializer).
-     * @param ttlSeconds - Optional expiry in seconds; omit for no expiration.
+     * @param ttlSeconds - Optional expiry in seconds, a safe integer of at least 1; omit for
+     *   no expiration.
      * @returns Resolves once the write completes.
      * @throws {CacheException} `SERIALIZATION_FAILED` when `value` cannot be encoded.
+     * @throws {CacheException} `INVALID_TTL` when `ttlSeconds` is not a safe integer of at least 1.
      */
     set<T>(prefix: string, id: string, value: T, ttlSeconds?: number): Promise<void>;
     /**
@@ -602,8 +604,10 @@ declare class CacheService {
      * @param prefix - Entity-group prefix.
      * @param id - Entity id.
      * @param value - The raw string to store as-is.
-     * @param ttlSeconds - Optional expiry in seconds; omit for no expiration.
+     * @param ttlSeconds - Optional expiry in seconds, a safe integer of at least 1; omit for
+     *   no expiration.
      * @returns Resolves once the write completes.
+     * @throws {CacheException} `INVALID_TTL` when `ttlSeconds` is not a safe integer of at least 1.
      */
     setRaw(prefix: string, id: string, value: string, ttlSeconds?: number): Promise<void>;
     /**
@@ -613,9 +617,11 @@ declare class CacheService {
      * @param prefix - Entity-group prefix.
      * @param id - Entity id.
      * @param value - The value to store (passed through the serializer).
-     * @param ttlSeconds - Optional expiry in seconds applied on the same atomic write.
+     * @param ttlSeconds - Optional expiry in seconds applied on the same atomic write, a safe
+     *   integer of at least 1.
      * @returns `true` when the value was stored, `false` when the key already existed.
      * @throws {CacheException} `SERIALIZATION_FAILED` when `value` cannot be encoded.
+     * @throws {CacheException} `INVALID_TTL` when `ttlSeconds` is not a safe integer of at least 1.
      */
     setNx<T>(prefix: string, id: string, value: T, ttlSeconds?: number): Promise<boolean>;
     /**
@@ -667,8 +673,10 @@ declare class CacheService {
      *
      * @param prefix - Entity-group prefix.
      * @param id - Entity id.
-     * @param ttlSeconds - Expiry in seconds.
+     * @param ttlSeconds - Expiry in seconds, a safe integer. As in Redis, zero or a negative
+     *   value deletes the key.
      * @returns `true` when the timeout was set, `false` when the key does not exist.
+     * @throws {CacheException} `INVALID_TTL` when `ttlSeconds` is not a safe integer.
      */
     expire(prefix: string, id: string, ttlSeconds: number): Promise<boolean>;
     /**
@@ -809,6 +817,9 @@ declare class CacheService {
      * @param prefix - Entity-group prefix.
      * @param pattern - Glob pattern for the id segment, e.g. `'*'`.
      * @returns The matching fully-namespaced keys.
+     * @throws {CacheException} `UNSUPPORTED_IN_CLUSTER` when called in cluster mode:
+     *   `KEYS` carries no key, so the cluster client sends it to one sampled node and the
+     *   reply would cover only that node's share of the keyspace.
      * @example
      * ```ts
      * await cache.keys('users', '*') // ['app:users:u_1', 'app:users:u_2']
@@ -971,9 +982,9 @@ declare class JsonSerializer implements ISerializer {
      * @param raw - The JSON string to decode.
      * @returns The decoded value, typed as `T`.
      * @throws {CacheException} `DESERIALIZATION_FAILED` when `raw` is not valid
-     *   JSON. `details.preview` carries at most {@link MAX_PREVIEW_LENGTH}
-     *   characters of `raw` (truncated with an ellipsis) to aid debugging without
-     *   leaking a large payload that may contain PII.
+     *   JSON. `details` holds a fixed `error` text and the `length` of `raw`; no
+     *   part of the stored value is echoed, as it may carry PII or a credential
+     *   (CLAUDE.md §4).
      */
     deserialize<T>(raw: string): T;
 }
@@ -1199,6 +1210,7 @@ declare const CACHE_ERROR_CODES: {
     readonly SCOPE_NOT_FOUND: "cache.scope_not_found";
     readonly SCOPE_NOT_READABLE: "cache.scope_not_readable";
     readonly KEY_NOT_IN_SCOPE: "cache.key_not_in_scope";
+    readonly INVALID_TTL: "cache.invalid_ttl";
 };
 /** Union of every cache error code string value. */
 type CacheErrorCode = (typeof CACHE_ERROR_CODES)[keyof typeof CACHE_ERROR_CODES];