@nestjs-pipeline/cache 0.2.0 → 0.2.1

package/README.md

@@ -468,6 +468,8 @@ The behavior records diagnostics on `context.items`:
 
 Exported as unique `Symbol` constants (`CACHE_HIT_ITEM` and `CACHE_KEY_ITEM`) to prevent key collisions in `context.items`. `CACHE_HIT_ITEM_TOKEN` and `CACHE_KEY_ITEM_TOKEN` are typed tokens over the same keys for `getPipelineItem` / `requirePipelineItem` from `@nestjs-pipeline/core`.
 
+`buildCacheAttributes(context)` turns the hit flag into the attribute `cache.hit`. Use it for span attributes through `AttributesBehavior` of [`@nestjs-pipeline/opentelemetry`](https://github.com/aristoteliss/nestjs-pipeline/tree/master/packages/pipeline-opentelemetry#attributes-from-other-behaviors), for audit `metadata`, or on a log line; it needs no telemetry package. It returns `{}` when the behavior did not run, never a fabricated miss, and never includes the key.
+
 
 ---
 
@@ -545,6 +547,7 @@ import {
   CACHE_KEY_ITEM_TOKEN,
   CacheManagerAdapter,
   buildCache,
+  buildCacheAttributes,
   buildKeyv,
   createPartitionedCacheKeyFactory,
   MissingCachePartitionError,

package/dist/helpers/build-attributes.d.ts

@@ -0,0 +1,36 @@
+import { type IPipelineContext } from '@nestjs-pipeline/core';
+/**
+ * The cache decision of one execution as flat attributes:
+ * `{ 'cache.hit': boolean }` once `CacheBehavior` looked the response up, and
+ * `{}` when it did not run, so a request without caching never reports a
+ * fabricated miss. The cache key is never included: it carries the tenant and
+ * the principal, and is unbounded as a value.
+ *
+ * The result is plain data and needs no telemetry package: put it on a span, a
+ * log line, an audit record or a metric label (bounded values only).
+ *
+ * @param context - The pipeline execution, read after `CacheBehavior` ran.
+ * @returns The attributes; empty when the behavior did not run.
+ *
+ * @example Span attributes, with `AttributesBehavior` of `@nestjs-pipeline/opentelemetry`
+ * ```ts
+ * PipelineModule.forRoot({
+ *   globalBehaviors: {
+ *     before: [TraceBehavior, [AttributesBehavior, { factories: [buildCacheAttributes] }]],
+ *   },
+ * });
+ * ```
+ *
+ * @example A log line from a custom behavior, after the chain ran
+ * ```ts
+ * async handle(context: IPipelineContext, next: NextDelegate) {
+ *   try {
+ *     return await next();
+ *   } finally {
+ *     this.logger.log({ request: context.requestName, ...buildCacheAttributes(context) });
+ *   }
+ * }
+ * ```
+ */
+export declare function buildCacheAttributes(context: IPipelineContext): Record<string, boolean>;
+//# sourceMappingURL=build-attributes.d.ts.map

package/dist/helpers/build-attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-attributes.d.ts","sourceRoot":"","sources":["../../src/helpers/build-attributes.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,uBAAuB,CAAC;AAG/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,gBAAgB,GACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIzB"}

package/dist/helpers/build-attributes.js

@@ -0,0 +1,45 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCacheAttributes = buildCacheAttributes;
+const core_1 = require("@nestjs-pipeline/core");
+const cache_behavior_1 = require("../cache.behavior");
+/**
+ * The cache decision of one execution as flat attributes:
+ * `{ 'cache.hit': boolean }` once `CacheBehavior` looked the response up, and
+ * `{}` when it did not run, so a request without caching never reports a
+ * fabricated miss. The cache key is never included: it carries the tenant and
+ * the principal, and is unbounded as a value.
+ *
+ * The result is plain data and needs no telemetry package: put it on a span, a
+ * log line, an audit record or a metric label (bounded values only).
+ *
+ * @param context - The pipeline execution, read after `CacheBehavior` ran.
+ * @returns The attributes; empty when the behavior did not run.
+ *
+ * @example Span attributes, with `AttributesBehavior` of `@nestjs-pipeline/opentelemetry`
+ * ```ts
+ * PipelineModule.forRoot({
+ *   globalBehaviors: {
+ *     before: [TraceBehavior, [AttributesBehavior, { factories: [buildCacheAttributes] }]],
+ *   },
+ * });
+ * ```
+ *
+ * @example A log line from a custom behavior, after the chain ran
+ * ```ts
+ * async handle(context: IPipelineContext, next: NextDelegate) {
+ *   try {
+ *     return await next();
+ *   } finally {
+ *     this.logger.log({ request: context.requestName, ...buildCacheAttributes(context) });
+ *   }
+ * }
+ * ```
+ */
+function buildCacheAttributes(context) {
+    return (0, core_1.hasPipelineItem)(context, cache_behavior_1.CACHE_HIT_ITEM_TOKEN)
+        ? { 'cache.hit': (0, core_1.getPipelineItem)(context, cache_behavior_1.CACHE_HIT_ITEM_TOKEN) === true }
+        : {};
+}
+//# sourceMappingURL=build-attributes.js.map

package/dist/helpers/build-attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-attributes.js","sourceRoot":"","sources":["../../src/helpers/build-attributes.ts"],"names":[],"mappings":";AAAA,sEAAsE;;AA0CtE,oDAMC;AA9CD,gDAI+B;AAC/B,sDAAyD;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,SAAgB,oBAAoB,CAClC,OAAyB;IAEzB,OAAO,IAAA,sBAAe,EAAC,OAAO,EAAE,qCAAoB,CAAC;QACnD,CAAC,CAAC,EAAE,WAAW,EAAE,IAAA,sBAAe,EAAC,OAAO,EAAE,qCAAoB,CAAC,KAAK,IAAI,EAAE;QAC1E,CAAC,CAAC,EAAE,CAAC;AACT,CAAC"}

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { CACHE_HIT_ITEM, CACHE_HIT_ITEM_TOKEN, CACHE_KEY_ITEM, CACHE_KEY_ITEM_TO
 export { CacheModule } from './cache.module';
 export { CACHE_DEFAULT_OPTIONS, PIPELINE_CACHE } from './constants/tokens';
 export { type CachePartitionDimension, MissingCachePartitionError, } from './errors/missing-partition.error';
+export { buildCacheAttributes } from './helpers/build-attributes';
 export { type CacheIntentOptions, cache, } from './helpers/cache.intent';
 export { buildCache, buildKeyv } from './helpers/cache-factory';
 export { createPartitionedCacheKeyFactory, type PartitionedCacheKeyOptions, } from './helpers/cache-key';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,mBAAmB,EACnB,KAAK,cAAc,GACpB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,aAAa,GACd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EACL,KAAK,uBAAuB,EAC5B,0BAA0B,GAC3B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,GACN,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EACL,gCAAgC,EAChC,KAAK,0BAA0B,GAChC,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,GACf,MAAM,sCAAsC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,mBAAmB,EACnB,KAAK,cAAc,GACpB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,aAAa,GACd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EACL,KAAK,uBAAuB,EAC5B,0BAA0B,GAC3B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,GACN,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EACL,gCAAgC,EAChC,KAAK,0BAA0B,GAChC,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,GACf,MAAM,sCAAsC,CAAC"}

package/dist/index.js

@@ -1,7 +1,7 @@
 "use strict";
 /* Copyright (C) 2026-present Aristotelis — see repository license. */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createPartitionedCacheKeyFactory = exports.buildKeyv = exports.buildCache = exports.cache = exports.MissingCachePartitionError = exports.PIPELINE_CACHE = exports.CACHE_DEFAULT_OPTIONS = exports.CacheModule = exports.CacheBehavior = exports.CACHE_KEY_ITEM_TOKEN = exports.CACHE_KEY_ITEM = exports.CACHE_HIT_ITEM_TOKEN = exports.CACHE_HIT_ITEM = exports.CacheManagerAdapter = void 0;
+exports.createPartitionedCacheKeyFactory = exports.buildKeyv = exports.buildCache = exports.cache = exports.buildCacheAttributes = exports.MissingCachePartitionError = exports.PIPELINE_CACHE = exports.CACHE_DEFAULT_OPTIONS = exports.CacheModule = exports.CacheBehavior = exports.CACHE_KEY_ITEM_TOKEN = exports.CACHE_KEY_ITEM = exports.CACHE_HIT_ITEM_TOKEN = exports.CACHE_HIT_ITEM = exports.CacheManagerAdapter = void 0;
 var cache_manager_adapter_1 = require("./adapters/cache-manager.adapter");
 Object.defineProperty(exports, "CacheManagerAdapter", { enumerable: true, get: function () { return cache_manager_adapter_1.CacheManagerAdapter; } });
 var cache_behavior_1 = require("./cache.behavior");
@@ -17,6 +17,8 @@ Object.defineProperty(exports, "CACHE_DEFAULT_OPTIONS", { enumerable: true, get:
 Object.defineProperty(exports, "PIPELINE_CACHE", { enumerable: true, get: function () { return tokens_1.PIPELINE_CACHE; } });
 var missing_partition_error_1 = require("./errors/missing-partition.error");
 Object.defineProperty(exports, "MissingCachePartitionError", { enumerable: true, get: function () { return missing_partition_error_1.MissingCachePartitionError; } });
+var build_attributes_1 = require("./helpers/build-attributes");
+Object.defineProperty(exports, "buildCacheAttributes", { enumerable: true, get: function () { return build_attributes_1.buildCacheAttributes; } });
 var cache_intent_1 = require("./helpers/cache.intent");
 Object.defineProperty(exports, "cache", { enumerable: true, get: function () { return cache_intent_1.cache; } });
 var cache_factory_1 = require("./helpers/cache-factory");

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AAEtE,0EAG0C;AAFxC,4HAAA,mBAAmB,OAAA;AAGrB,mDAM0B;AALxB,gHAAA,cAAc,OAAA;AACd,sHAAA,oBAAoB,OAAA;AACpB,gHAAA,cAAc,OAAA;AACd,sHAAA,oBAAoB,OAAA;AACpB,+GAAA,aAAa,OAAA;AAEf,+CAA6C;AAApC,2GAAA,WAAW,OAAA;AACpB,6CAA2E;AAAlE,+GAAA,qBAAqB,OAAA;AAAE,wGAAA,cAAc,OAAA;AAC9C,4EAG0C;AADxC,qIAAA,0BAA0B,OAAA;AAE5B,uDAGgC;AAD9B,qGAAA,KAAK,OAAA;AAEP,yDAAgE;AAAvD,2GAAA,UAAU,OAAA;AAAE,0GAAA,SAAS,OAAA;AAC9B,iDAG6B;AAF3B,6HAAA,gCAAgC,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AAEtE,0EAG0C;AAFxC,4HAAA,mBAAmB,OAAA;AAGrB,mDAM0B;AALxB,gHAAA,cAAc,OAAA;AACd,sHAAA,oBAAoB,OAAA;AACpB,gHAAA,cAAc,OAAA;AACd,sHAAA,oBAAoB,OAAA;AACpB,+GAAA,aAAa,OAAA;AAEf,+CAA6C;AAApC,2GAAA,WAAW,OAAA;AACpB,6CAA2E;AAAlE,+GAAA,qBAAqB,OAAA;AAAE,wGAAA,cAAc,OAAA;AAC9C,4EAG0C;AADxC,qIAAA,0BAA0B,OAAA;AAE5B,+DAAkE;AAAzD,wHAAA,oBAAoB,OAAA;AAC7B,uDAGgC;AAD9B,qGAAA,KAAK,OAAA;AAEP,yDAAgE;AAAvD,2GAAA,UAAU,OAAA;AAAE,0GAAA,SAAS,OAAA;AAC9B,iDAG6B;AAF3B,6HAAA,gCAAgC,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestjs-pipeline/cache",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Caching behavior for the NestJS pipeline — cache-manager v7 on top of Keyv with pluggable stores (memory, redis, memcache, sqlite, postgres).",
   "author": "Aristotelis <aristotelis@ik.me>",
   "license": "SEE LICENSE IN LICENSE",