@bymax-one/nest-cache 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -4,6 +4,76 @@ All notable changes to this project are documented in this file. The format is
 based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.2] - 2026-09-04
+
+### Changed
+
+- **Nothing you execute changes.** `dist/` built from this tag is byte-for-byte
+  identical to 1.2.1 — verified by unpacking the published 1.2.1 tarball and
+  diffing it against a fresh build, not asserted. `src/` has not been touched
+  since 1.2.1.
+
+  Two files in an installed copy do differ, and neither is code: the `version`
+  field in `package.json`, and this changelog. Upgrading from 1.2.1 changes no
+  behaviour; staying on 1.2.1 costs you nothing.
+
+  The version exists because the repository moved underneath the artifact, and a
+  released tag is where that movement is recorded.
+
+### Security
+
+- **Three advisory fixes, all in development dependencies.** `browserslist` to
+  4.28.8 (GHSA-73wf-gq98-2v4g, GHSA-c83g-rgw3-j3cx), `fast-uri` to 3.1.6 (four
+  advisories at CVSS 7.5) and `qs` to 6.16.0 (GHSA-4mjr-xmp4-gh2g,
+  GHSA-x5fp-wj9c-mxmx). All three are reached through `@stryker-mutator/*`, which
+  is a devDependency, and this package publishes with `"dependencies": {}`.
+
+  **No consumer was exposed and none is protected by this release.** The fixes
+  protect the build environment. They are listed because "Security" in a changelog
+  is read as "upgrade for this", and here that reading would be wrong.
+
+  Two of the three were already pinned in `overrides` at floors that already
+  admitted the fixed versions, and protected nothing: a caret there is a floor
+  applied when resolution happens, not a standing instruction to re-resolve. The
+  check that works is the resolved version in the lockfile, never the presence of
+  an entry.
+
+### Internal
+
+- ESLint 9 to 10, with `eslint-plugin-import` replaced by the maintained fork
+  `eslint-plugin-import-x`. The 9 line is end-of-life: 9.39.5 is the last release
+  and is itself deprecated, and the `maintenance` dist-tag points at it.
+- `import-x/parsers` is now configured, which fixes a rule that had never worked.
+  `no-cycle` was declared `error` and reported as active by `--print-config` while
+  a real two-file cycle passed with exit 0, because the dependency parser skips in
+  silence every extension it cannot map. No cycles exist in `src/`; the gate was
+  simply open.
+- `@parcel/watcher`'s build script is recorded as denied, so `pnpm install` stops
+  failing on it under pnpm 11.
+- The shared Bymax code-review rules are adopted in `AGENTS.md`, kept in step by
+  the `agents-sync` workflow.
+
+## [1.2.1] - 2026-08-21
+
+### Changed
+
+- **`RevealedValue`'s hash arm now names each entry `field`, not `name`**
+  (`{ field, value }`). Redis's own vocabulary for a hash is field/value —
+  `HSET key field value`, `HDEL key field`, and `HGETALL` returns field-value
+  pairs — so a generic `name` lost the domain term in the one place a reader
+  would check the shape against the server's documentation.
+
+  This is a **type-level breaking change** shipped as a patch, deliberately and
+  with the trade-off stated: `RevealedValue` was published in 1.2.0 roughly an
+  hour earlier, no consumer had wired it yet, and correcting a freshly published
+  name is cheaper than carrying a permanent vocabulary mismatch or maintaining
+  two names for one concept. A consumer that already destructured `name` gets a
+  compile error, not a silent behaviour change.
+
+  The library emits **one** name. Aliasing `field` and `name` together would have
+  been two names for one idea, which is the defect this corrects rather than a
+  softer way to ship it.
+
 ## [1.2.0] - 2026-08-21
 
 ### Security
@@ -280,6 +350,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
 
+[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
 [1.2.0]: https://github.com/bymaxone/nest-cache/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/bymaxone/nest-cache/compare/v1.0.6...v1.1.0
 [1.0.6]: https://github.com/bymaxone/nest-cache/compare/v1.0.5...v1.0.6

package/README.md

@@ -473,6 +473,47 @@ Do not relax this to be helpful. Widening it later is compatible; a leak is not
 
 `mode`, `isScanSupported` and `degradedAboveMs` sit **outside** the health union: a cluster deployment that is down should still report that scanning was never going to work.
 
+### Reading a value: `revealed` / `withheld` / `missing`
+
+`revealValue()` answers with a discriminated union, not a nullable value, because **"I may not tell you" and "there is nothing here" are different answers** and rendering them identically is the defect this whole surface exists to avoid.
+
+```ts
+import type { CacheAdminService } from '@bymax-one/nest-cache/admin'
+
+async function describeValue(admin: CacheAdminService, scope: string, key: string) {
+  const result = await admin.revealValue(scope, key)
+
+  switch (result.status) {
+    case 'revealed':
+      // `result.type` is the Redis type; `result.value` is shaped by it.
+      return { type: result.type, value: result.value }
+    case 'withheld':
+      // The scope declares `isReadable: false`. `origin` explains why, verbatim.
+      // Listing, types, TTLs and sizes for this key remain available.
+      return { refusedBecause: result.origin }
+    case 'missing':
+      return { gone: true }
+  }
+}
+```
+
+A withheld value is **not an authorization failure**. The caller is allowed to ask; the deployment declared the keyspace unreadable at wiring, and no credential changes that — so serving it as `403` would tell a client that some other permission would unlock it, which is false.
+
+The revealed value is shaped by the key's type:
+
+| `value.kind`  | Shape                              | Notes                                                                                    |
+| ------------- | ---------------------------------- | ---------------------------------------------------------------------------------------- |
+| `string`      | `{ value: string }`                | Truncated to `revealStringLimit`                                                         |
+| `hash`        | `{ fields: { field, value }[] }`   | `field`, matching Redis's own vocabulary (`HSET key field value`)                        |
+| `members`     | `{ members: string[] }`            | **Sets and lists both.** The enclosing `type` says which — see the ordering caveat below |
+| `scored`      | `{ members: { member, score }[] }` | Sorted sets. `score` is a **string**: parsing to a number would round large integers     |
+| `unsupported` | `{ type: RedisKeyType }`           | Streams and module types — says so, rather than returning an empty value                 |
+
+Every arm except `unsupported` carries `isComplete`. It is deliberately **positive polarity**: an absent boolean reads as `false`, and under a name like `truncated` that default would be the _reassuring_ answer — a value silently claiming nothing was cut.
+
+> [!IMPORTANT]
+> **List order is meaningful; set order is not**, and both arrive in the same `members` array. Nothing in the type stops a renderer from sorting either one. Sorting a set for display is fine; sorting a list is a lie about the data — an `LPUSH` queue shown alphabetically misreports what pops next. Gate any client-side ordering on `type === 'set'`.
+
 ### Costs the surface does not hide
 
 - **`sampledCount` / `sampledBytes`** are sums over a capped `SCAN`, not measurements of the keyspace. `isComplete` is the fact; the names are the guard.

package/dist/admin/index.cjs

@@ -391,7 +391,11 @@ exports.CacheAdminService = class CacheAdminService {
         const kept = all.slice(0, limit);
         return {
           kind: "hash",
-          fields: kept.map(([name, value]) => ({ name, value })),
+          // `field`, not `name`: Redis's own vocabulary for a hash is field/value
+          // (`HSET key field value`, `HDEL key field`). A generic `name` loses the
+          // domain term in the one place a reader would check it against the
+          // server's documentation.
+          fields: kept.map(([field, value]) => ({ field, value })),
           isComplete: kept.length === all.length
         };
       }

package/dist/admin/index.d.cts

@@ -596,7 +596,7 @@ type RevealedValue = {
 } | {
     readonly kind: 'hash';
     readonly fields: readonly {
-        readonly name: string;
+        readonly field: string;
         readonly value: string;
     }[];
     readonly isComplete: boolean;

package/dist/admin/index.d.ts

@@ -596,7 +596,7 @@ type RevealedValue = {
 } | {
     readonly kind: 'hash';
     readonly fields: readonly {
-        readonly name: string;
+        readonly field: string;
         readonly value: string;
     }[];
     readonly isComplete: boolean;

package/dist/admin/index.mjs

@@ -389,7 +389,11 @@ var CacheAdminService = class {
         const kept = all.slice(0, limit);
         return {
           kind: "hash",
-          fields: kept.map(([name, value]) => ({ name, value })),
+          // `field`, not `name`: Redis's own vocabulary for a hash is field/value
+          // (`HSET key field value`, `HDEL key field`). A generic `name` loses the
+          // domain term in the one place a reader would check it against the
+          // server's documentation.
+          fields: kept.map(([field, value]) => ({ field, value })),
           isComplete: kept.length === all.length
         };
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-cache",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "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",
@@ -111,7 +111,7 @@
     "@arethetypeswrong/cli": "^0.18.5",
     "@commitlint/cli": "^21.2.1",
     "@commitlint/config-conventional": "^21.2.0",
-    "@eslint/js": "^9.39.4",
+    "@eslint/js": "^10.0.1",
     "@nestjs/common": "^11.1.20",
     "@nestjs/core": "^11.1.20",
     "@nestjs/testing": "^11.1.20",
@@ -122,10 +122,10 @@
     "@types/node": "^24",
     "@typescript-eslint/eslint-plugin": "^8.59.3",
     "@typescript-eslint/parser": "^8.59.3",
-    "eslint": "^9.39.4",
+    "eslint": "^10.9.1",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-import-resolver-typescript": "^4.4.4",
-    "eslint-plugin-import": "^2.32.0",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-import-x": "^4.17.1",
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-security": "^4.0.0",
     "globals": "^17.6.0",