@bymax-one/nest-cache 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.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 +301,7 @@ 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.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.1",
   "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",