@bymax-one/nest-cache 1.2.2 → 1.2.4

package/dist/server/index.mjs

@@ -65,7 +65,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
@@ -106,12 +107,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, HttpStatus.GATEWAY_TIMEOUT],
   [CACHE_ERROR_CODES.CONNECTION_LOST, HttpStatus.SERVICE_UNAVAILABLE],
   [CACHE_ERROR_CODES.INVALID_KEY, HttpStatus.BAD_REQUEST],
+  [CACHE_ERROR_CODES.INVALID_TTL, HttpStatus.BAD_REQUEST],
   [CACHE_ERROR_CODES.FLUSH_DISABLED_IN_PRODUCTION, HttpStatus.FORBIDDEN]
 ]);
 var CacheException = class extends HttpException {
@@ -709,7 +715,7 @@ KeyBuilder = __decorateClass([
   Injectable(),
   __decorateParam(0, Inject(BYMAX_CACHE_OPTIONS))
 ], 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);
 var JsonSerializer = class {
   /**
@@ -751,17 +757,17 @@ var JsonSerializer = class {
    * @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
       });
     }
   }
@@ -777,6 +783,17 @@ var resolveSerializer = (options, injected) => (
   options.serializer ?? injected ?? new 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;
@@ -837,14 +854,17 @@ var CacheService = class {
    * @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);
@@ -856,12 +876,15 @@ var CacheService = class {
    * @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);
@@ -874,13 +897,16 @@ var CacheService = class {
    * @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";
   }
@@ -952,10 +978,13 @@ var CacheService = class {
    *
    * @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;
   }
@@ -1163,6 +1192,9 @@ var CacheService = class {
    * @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']
@@ -1170,7 +1202,11 @@ var CacheService = class {
    */
   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/shared/index.cjs

@@ -20,7 +20,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/shared/constants/event-names.ts

package/dist/shared/index.d.cts

@@ -97,6 +97,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/shared/index.d.ts

@@ -97,6 +97,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/shared/index.mjs

@@ -18,7 +18,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/shared/constants/event-names.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-cache",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Typed Redis cache for NestJS based on ioredis 6, with namespace strategy, Pub/Sub and Lua script management.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",