@bymax-one/nest-cache 1.2.3 → 1.2.4

package/CHANGELOG.md

@@ -6,6 +6,72 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [1.2.4] - 2026-10-31
+
+Two calls now refuse input they could not honor, one error code is added, and the documentation catches up with the code.
+
+### Added
+
+- **`CACHE_ERROR_CODES.INVALID_TTL` (`cache.invalid_ttl`, HTTP 400)**, thrown for a TTL the library refuses. See Changed.
+
+### Changed
+
+- **`CacheService.keys()` is refused in cluster mode.** `KEYS` carries no key, so the cluster client sends
+  it to one sampled node and the reply listed only that node's share of the keyspace, with no sign that it
+  was partial. It now throws `UNSUPPORTED_IN_CLUSTER` with `details.operation: 'keys'`, like `scan`,
+  `getClient` and `flushNamespace`. **Apply to a consumer.** A cluster deployment that called `keys()`
+  must iterate with `scan` on each node through its own client, or avoid listing keys; standalone and
+  sentinel are unchanged.
+- **`ttlSeconds` is validated, with a new error code, `cache.invalid_ttl` (HTTP 400).** `set`, `setRaw`
+  and `setNx` need a safe integer of at least 1, or none for no expiry; `expire` needs a safe integer,
+  and zero or a negative one still deletes the key, as in Redis. Anything else throws `CacheException`
+  with `INVALID_TTL` and `details.reason` set to `not_a_safe_integer` or `below_minimum`, before a command
+  is sent. **Apply to a consumer.** What now throws `INVALID_TTL`: `set`, `setRaw`, `setNx` with `0`, a negative number, a fraction, `NaN`, `Infinity` or an integer above 2^53; `expire` with a fraction, `NaN`, `Infinity` or an integer above 2^53. Redis documents `SET ... EX` as a positive integer and `EXPIRE` as an
+  integer, and answers anything else with a raw reply error that carries no `cache.*` code, so the values
+  refused here already failed. The one exception is an integer above 2^53 seconds, a TTL of about 285
+  million years, which this refuses and Redis may accept. Code that caught the raw error by its message
+  should switch to `error.code === 'cache.invalid_ttl'`.
+
+### Deprecated
+
+- **Implementation helpers exported from `@bymax-one/nest-cache/admin`** are marked `@deprecated` and will
+  leave the public surface in 2.0.0: `validateScopes`, `findScope`, `isKeyInScope`, `readScopePattern`,
+  `resolveAdminOptions`, `ResolvedAdminOptions`, `parseInfoFields`, `readRedisStats`, `readKeyTtl`,
+  `readKeyType`, `readSizeBytes`, `IRedisReader`, `IRedisReaderSource`, `IRedisPipeline`,
+  `PipelineReply` and `ICacheProbe`. They keep working in 1.x. Do not depend on them.
+
+### Documentation
+
+- The README error-code table described `cache.shutdown_timeout` as thrown when `quit()` exceeds
+  `shutdownTimeoutMs`. It never reaches the caller: the library forces `disconnect()` and emits an
+  `error` event with `reason: 'forced_disconnect'`. The row now says so.
+- The README states that `app.enableShutdownHooks()` is required for the graceful shutdown to run, and
+  carries a warning that `/admin` has no authentication of its own. It documents the `/admin` options
+  and their defaults and the exported types, constants and tokens it left out, lists `keys` among the
+  cluster-refused calls, and marks the three codes the library never throws as reserved.
+- The sentinel example passed `process.env.REDIS_PASSWORD` as `password`, which does not compile
+  for a consumer that enables `exactOptionalPropertyTypes`. It now falls back to an empty string,
+  which ioredis treats like no password.
+
+### Tests
+
+- `src/readme.spec.ts` parses the README's option-defaults table and error-code table and asserts them
+  against the resolved defaults, the minimum timeouts, `CACHE_ERROR_CODES` and the status each
+  `CacheException` carries, so a README that drifts from the code fails CI.
+
+### Internal
+
+- `check:published` compiles every README snippet, not only the ones that import the package, through the
+  TypeScript API so a syntax error in one snippet no longer hides the type errors in the others. A
+  snippet that omits its import is given the package's public names, and the names a snippet takes from
+  the surrounding prose are typed in `scripts/readme-prelude.d.ts`, so a wrong method, option or field is
+  an error instead of a call on `any`.
+- The same gate no longer excuses a wrong method on an imported type or on a union-typed value as a
+  class the README abbreviates, and a relative import in a snippet that resolves to nothing fails it.
+- The same gate now checks the typed names the snippets rely on, so a name in that declaration file that
+  stops resolving is an error instead of silently becoming `any`, and it tolerates a parse error only
+  where the parse tree shows a `...` elision, so a genuine syntax error in a snippet fails it.
+
 ## [1.2.3] - 2026-10-30
 
 ### Changed
@@ -394,7 +460,8 @@ type or export moved.
 - Published with npm OIDC provenance — no long-lived tokens
 - Zero direct runtime dependencies (`dependencies: {}`) — `ioredis` and NestJS via peer deps
 
-[Unreleased]: https://github.com/bymaxone/nest-cache/compare/v1.2.3...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-cache/compare/v1.2.4...HEAD
+[1.2.4]: https://github.com/bymaxone/nest-cache/compare/v1.2.3...v1.2.4
 [1.2.3]: https://github.com/bymaxone/nest-cache/compare/v1.2.2...v1.2.3
 [1.2.2]: https://github.com/bymaxone/nest-cache/compare/v1.2.1...v1.2.2
 [1.2.1]: https://github.com/bymaxone/nest-cache/compare/v1.2.0...v1.2.1

package/README.md

@@ -171,7 +171,7 @@ BymaxCacheModule.forRoot({
       { host: 'sentinel2.example.com', port: 26379 }
     ],
     name: 'mymaster',
-    password: process.env.REDIS_PASSWORD
+    password: process.env.REDIS_PASSWORD ?? ''
   },
   namespace: 'app'
 })
@@ -219,6 +219,15 @@ import { BymaxCacheModule } from '@bymax-one/nest-cache'
 export class AppModule {}
 ```
 
+> [!IMPORTANT]
+> **Call `app.enableShutdownHooks()` in `main.ts`.** Nest runs `OnModuleDestroy` on `SIGTERM` / `SIGINT` only when shutdown hooks are enabled. Without it the process exits on a signal without quitting the Redis connection gracefully, and `shutdownTimeoutMs` never comes into play.
+
+```typescript
+const app = await NestFactory.create(AppModule)
+app.enableShutdownHooks()
+await app.listen(3000)
+```
+
 ### 3. Inject `CacheService`
 
 The module is global by default, so no re-import is needed in feature modules:
@@ -420,6 +429,9 @@ export class HealthController {
 
 A read-only surface for an operator-facing console: is the cache answering, what is it doing, what is in it.
 
+> [!WARNING]
+> **`/admin` has no authentication or authorization of its own.** The library registers services, not routes: `CacheStatusService` and `CacheAdminService` list keys, report `INFO` statistics and, for a readable scope, return stored values to whoever calls them. Put every route you build on them behind your own guard (an authenticated operator role), and never on a public route.
+
 ```ts
 import { BymaxCacheModule } from '@bymax-one/nest-cache'
 import { BymaxCacheAdminModule } from '@bymax-one/nest-cache/admin'
@@ -471,6 +483,21 @@ await this.admin.listKeys('cache', { includeSize: true })
 await this.admin.revealValue('auth', 'auth:sess:1')  // { status: 'withheld', origin }
 ```
 
+### Options
+
+| Option              | Type                    | Default | Description                                                              |
+| ------------------- | ----------------------- | ------- | ------------------------------------------------------------------------ |
+| `scopes`            | `readonly CacheScope[]` | —       | The keyspaces this deployment exposes; required                          |
+| `degradedAboveMs`   | `number`                | `250`   | Probe latency above which `health()` reports `degraded`                  |
+| `probeTimeoutMs`    | `number`                | `2000`  | How long `health()` waits for `PING` before reporting `down`             |
+| `scanLimit`         | `number`                | `500`   | Entries one `listKeys` page may carry (a page can slightly exceed it)    |
+| `commandBatchLimit` | `number`                | `100`   | Commands in one pipeline batch                                           |
+| `revealLimit`       | `number`                | `200`   | Members or fields `revealValue` returns before `isComplete` is `false`   |
+| `revealStringLimit` | `number`                | `4096`  | Characters of a string value `revealValue` returns                       |
+| `isGlobal`          | `boolean`               | `false` | Register the admin module globally. The cache module's default is `true` |
+
+Every threshold must be a positive integer; one that is not fails the boot with `cache.invalid_scope`. `CacheAdminService` also has `listScopes()` and `describeKey(scope, key)`, which returns a key's type, TTL and whether its value is readable, without the value.
+
 ### What the library owns, and what you own
 
 The library owns the **mechanism**: validating the allowlist, scanning against it, describing keys, withholding values. The application owns **which keyspaces exist**, the `origin` prose that explains them, the routes, and the guards. A cache library cannot know that another library writes at Redis root through `getClient()`, and making it depend on that library to find out would invert two packages to save an application from stating one thing about itself.
@@ -646,7 +673,7 @@ Scripts are declared up front — through `options.scripts` or `ScriptManagerSer
 
 ### Cluster mode refuses commands it cannot honor safely
 
-`scan()`, `flushNamespace()`, and `getClient()` throw `UNSUPPORTED_IN_CLUSTER` under `mode: 'cluster'` rather than silently operating on one node. A partial flush that reports success is worse than an error.
+`scan()`, `keys()`, `flushNamespace()`, and `getClient()` throw `UNSUPPORTED_IN_CLUSTER` under `mode: 'cluster'` rather than silently operating on one node. `KEYS` carries no key, so the cluster client sends it to a single node and the reply would list only that node's share of the keyspace. A partial flush that reports success is worse than an error.
 
 ### Security Checklist
 
@@ -680,7 +707,7 @@ When integrating `@bymax-one/nest-cache` in production, verify each of the follo
 | Error Payloads        | Connection URLs omitted (may embed credentials); a stored value is never echoed (a fixed text and its length only)                                               |
 | Destructive Ops       | `flushNamespace()` blocked under `NODE_ENV=production` unless `allowFlushInProduction`; `SCAN` + `UNLINK`, namespace-scoped                                      |
 | Lua Execution         | Scripts registered by name; call sites pass keys/args only — request input never reaches a script body                                                           |
-| Cluster Safety        | `scan` / `flushNamespace` / `getClient` throw `UNSUPPORTED_IN_CLUSTER` instead of acting on a single node                                                        |
+| Cluster Safety        | `scan` / `keys` / `flushNamespace` / `getClient` throw `UNSUPPORTED_IN_CLUSTER` instead of acting on a single node                                               |
 | Transport             | `rediss://` sets TLS on the client; explicit `connection.tls` supported for custom CA / mTLS                                                                     |
 | Connection Resilience | Bounded `maxRetriesPerRequest`, `READONLY`-failover reconnect, graceful `quit()` with a shutdown timeout                                                         |
 | Supply Chain          | `"dependencies": {}` — no transitive runtime packages of the library's own choosing; published with npm provenance                                               |
@@ -746,6 +773,8 @@ pnpm lint          # ESLint
 | Namespace       | `flushNamespace` (prod-guarded)                        |
 | Health          | `isHealthy` · `ping` · `info`                          |
 
+**TTLs.** `ttlSeconds` on `set`, `setRaw` and `setNx` is a safe integer of at least `1`; omit it for no expiry. `expire` takes a safe integer, and as in Redis a zero or negative one deletes the key. Anything else throws `INVALID_TTL` before a command is sent.
+
 ### `PubSubService`
 
 `publish<T>(channel, message)` · `subscribe<T>(channel, handler)` · `psubscribe<T>(pattern, handler)`
@@ -758,33 +787,54 @@ pnpm lint          # ESLint
 
 `CacheException` (extends `HttpException`) + `CACHE_ERROR_CODES` (namespaced `cache.*`).
 
+### Types, constants and tokens
+
+From `@bymax-one/nest-cache`:
+
+| Export                                                                                          | What it is                                                                                  |
+| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `BymaxCacheModuleOptions`, `BymaxCacheModuleAsyncOptions`                                       | The options of `forRoot()` and `forRootAsync()`; the Configuration table lists their fields |
+| `BymaxCacheStandaloneConnection`, `BymaxCacheSentinelConnection`, `BymaxCacheClusterConnection` | The `connection`, `sentinel` and `cluster` blocks                                           |
+| `RedisOptions`, `ClusterOptions`, `ClusterNode`, `SentinelAddress`                              | The ioredis option types the blocks above refer to, re-exported                             |
+| `ResolvedOptions`                                                                               | The shape injected under `BYMAX_CACHE_OPTIONS`, with every default applied                  |
+| `IPubSubHandler`, `IPubSubPatternHandler`, `Unsubscribe`                                        | The handler signatures and the function `subscribe` / `psubscribe` return                   |
+| `CACHE_ERROR_MESSAGES`                                                                          | The default message of every code, keyed by code                                            |
+| `DEFAULT_NAMESPACE`, `DEFAULT_KEY_SEPARATOR`, `DEFAULT_REDIS_PORT`                              | `'app'`, `':'` and `6379`                                                                   |
+
+From `@bymax-one/nest-cache/shared` (also re-exported from the main entry): `CACHE_EVENT_NAMES`, `CacheEventName`, `CacheConnectionStatus`, `CacheErrorCode`, `CacheNamespace`, `CacheKeyPrefix` and `SerializableValue`.
+
+From `@bymax-one/nest-cache/admin`: `BymaxCacheAdminModuleOptions` and `BymaxCacheAdminModuleAsyncOptions` (the Options table above), `CacheScope`, `ListKeysOptions`, the result types `CacheHealth`, `CacheConfig`, `CacheMode`, `RedisStats`, `KeyspacePage`, `KeyEntry`, `KeyDetail`, `KeyTtl`, `RevealResult` and `RevealedValue`, the token `BYMAX_CACHE_ADMIN_OPTIONS`, and the defaults `DEFAULT_DEGRADED_ABOVE_MS`, `DEFAULT_PROBE_TIMEOUT_MS`, `DEFAULT_SCAN_LIMIT`, `DEFAULT_COMMAND_BATCH_LIMIT`, `DEFAULT_REVEAL_LIMIT` and `DEFAULT_REVEAL_STRING_LIMIT`.
+
+The other names `/admin` exports (the scope and `INFO` helpers such as `validateScopes` and `readRedisStats`, `resolveAdminOptions`, and the reader contracts) are implementation helpers, marked `@deprecated`: they will leave the public surface in 2.0.0, so do not depend on them.
+
 ---
 
 ## 🪪 Default Error Codes
 
 All errors are instances of `CacheException` and carry a stable `code` string from `CACHE_ERROR_CODES`:
 
-| Code                                 | HTTP | When thrown                                                                                                                               |
-| ------------------------------------ | ---- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `cache.connection_failed`            | 500  | Cannot connect after retries; also bootstrap validation of `connection` and timeouts                                                      |
-| `cache.command_timeout`              | 504  | Reserved; not currently thrown by the library                                                                                             |
-| `cache.connection_lost`              | 503  | Reserved; not currently thrown by the library                                                                                             |
-| `cache.deserialization_failed`       | 500  | Malformed payload in `get<T>`                                                                                                             |
-| `cache.serialization_failed`         | 500  | Unserializable value in `set<T>`                                                                                                          |
-| `cache.invalid_key`                  | 400  | Empty prefix or id (`build`), or empty key (`applyNamespace`)                                                                             |
-| `cache.invalid_namespace`            | 500  | Empty or whitespace-only namespace, empty `keySeparator`, namespace containing the separator or a glob metacharacter (`*`, `?`, `[`, `\`) |
-| `cache.script_not_registered`        | 500  | `eval(name)` before `register(name)`                                                                                                      |
-| `cache.script_execution_failed`      | 500  | Lua runtime error or NOSCRIPT retry failure                                                                                               |
-| `cache.script_registry_missing`      | 500  | `eval` called when no `ScriptManagerService` is wired                                                                                     |
-| `cache.flush_disabled_in_production` | 403  | `flushNamespace()` in prod without `allowFlushInProduction`                                                                               |
-| `cache.unsupported_in_cluster`       | 500  | `scan`, `flushNamespace`, or `getClient` called in cluster mode                                                                           |
-| `cache.cluster_misconfigured`        | 500  | `mode: 'cluster'` without `cluster.nodes`                                                                                                 |
-| `cache.sentinel_misconfigured`       | 500  | `mode: 'sentinel'` without `sentinel.sentinels`/`name`                                                                                    |
-| `cache.shutdown_timeout`             | 500  | `quit()` exceeded `shutdownTimeoutMs`                                                                                                     |
-| `cache.invalid_scope`                | 500  | `/admin` scope allowlist invalid at wiring                                                                                                |
-| `cache.scope_not_found`              | 500  | `/admin` call named an undeclared scope id                                                                                                |
-| `cache.scope_not_readable`           | 500  | Reserved; not currently thrown (unreadable scopes return `withheld`)                                                                      |
-| `cache.key_not_in_scope`             | 500  | `/admin` call named a key outside the named scope                                                                                         |
+| Code                                 | HTTP | When thrown                                                                                                                                                            |
+| ------------------------------------ | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cache.connection_failed`            | 500  | Cannot connect after retries; also bootstrap validation of `connection` and timeouts                                                                                   |
+| `cache.command_timeout`              | 504  | Reserved, never thrown today                                                                                                                                           |
+| `cache.connection_lost`              | 503  | Reserved, never thrown today                                                                                                                                           |
+| `cache.deserialization_failed`       | 500  | Malformed payload in `get<T>`                                                                                                                                          |
+| `cache.serialization_failed`         | 500  | Unserializable value in `set<T>`                                                                                                                                       |
+| `cache.invalid_key`                  | 400  | Empty prefix or id (`build`), or empty key (`applyNamespace`)                                                                                                          |
+| `cache.invalid_ttl`                  | 400  | `ttlSeconds` is not a safe integer, or is below 1 for `set` / `setRaw` / `setNx`                                                                                       |
+| `cache.invalid_namespace`            | 500  | Empty or whitespace-only namespace, empty `keySeparator`, namespace containing the separator or a glob metacharacter (`*`, `?`, `[`, `\`)                              |
+| `cache.script_not_registered`        | 500  | `eval(name)` before `register(name)`                                                                                                                                   |
+| `cache.script_execution_failed`      | 500  | Lua runtime error or NOSCRIPT retry failure                                                                                                                            |
+| `cache.script_registry_missing`      | 500  | `eval` called when no `ScriptManagerService` is wired                                                                                                                  |
+| `cache.flush_disabled_in_production` | 403  | `flushNamespace()` in prod without `allowFlushInProduction`                                                                                                            |
+| `cache.unsupported_in_cluster`       | 500  | `scan`, `keys`, `flushNamespace`, or `getClient` called in cluster mode                                                                                                |
+| `cache.cluster_misconfigured`        | 500  | `mode: 'cluster'` without `cluster.nodes`                                                                                                                              |
+| `cache.sentinel_misconfigured`       | 500  | `mode: 'sentinel'` without `sentinel.sentinels`/`name`                                                                                                                 |
+| `cache.shutdown_timeout`             | 500  | Internal, never thrown to the caller: `quit()` exceeded `shutdownTimeoutMs`, so the library forces `disconnect()` and emits `error` with `reason: 'forced_disconnect'` |
+| `cache.invalid_scope`                | 500  | `/admin` scope allowlist invalid at wiring                                                                                                                             |
+| `cache.scope_not_found`              | 500  | `/admin` call named an undeclared scope id                                                                                                                             |
+| `cache.scope_not_readable`           | 500  | Reserved, never thrown today (unreadable scopes return `withheld`)                                                                                                     |
+| `cache.key_not_in_scope`             | 500  | `/admin` call named a key outside the named scope                                                                                                                      |
 
 Full catalog and HTTP status mapping: [`docs/technical_specification.md §12`](./docs/technical_specification.md).
 

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 {
@@ -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']
@@ -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']
@@ -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.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 {
@@ -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.3",
+  "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",