@nestjs-pipeline/cache 0.2.0

package/dist/errors/missing-partition.error.d.ts

@@ -0,0 +1,18 @@
+import { MissingPartitionError } from '@nestjs-pipeline/core';
+/** Which dimension of the cache key could not be resolved. */
+export type CachePartitionDimension = 'tenant' | 'principal' | 'scope';
+/**
+ * Raised before the cache is consulted when a dimension required by the
+ * configured key factory cannot be resolved.
+ *
+ * A cache hit returns without executing the handler,
+ * so it also skips whatever entity-level authorization and field filtering that
+ * handler performs. A key missing its tenant or principal segment therefore does
+ * not merely lose isolation — it can replay one caller's authorized response to
+ * another.
+ */
+export declare class MissingCachePartitionError extends MissingPartitionError<CachePartitionDimension> {
+    readonly name = "MissingCachePartitionError";
+    constructor(requestName: string, dimension: CachePartitionDimension, remedy: string);
+}
+//# sourceMappingURL=missing-partition.error.d.ts.map

package/dist/errors/missing-partition.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-partition.error.d.ts","sourceRoot":"","sources":["../../src/errors/missing-partition.error.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,8DAA8D;AAC9D,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,CAAC;AAEvE;;;;;;;;;GASG;AACH,qBAAa,0BAA2B,SAAQ,qBAAqB,CAAC,uBAAuB,CAAC;IAC5F,SAAkB,IAAI,gCAAgC;gBAGpD,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,uBAAuB,EAClC,MAAM,EAAE,MAAM;CAIjB"}

package/dist/errors/missing-partition.error.js

@@ -0,0 +1,23 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MissingCachePartitionError = void 0;
+const core_1 = require("@nestjs-pipeline/core");
+/**
+ * Raised before the cache is consulted when a dimension required by the
+ * configured key factory cannot be resolved.
+ *
+ * A cache hit returns without executing the handler,
+ * so it also skips whatever entity-level authorization and field filtering that
+ * handler performs. A key missing its tenant or principal segment therefore does
+ * not merely lose isolation — it can replay one caller's authorized response to
+ * another.
+ */
+class MissingCachePartitionError extends core_1.MissingPartitionError {
+    name = 'MissingCachePartitionError';
+    constructor(requestName, dimension, remedy) {
+        super('Cache', requestName, dimension, remedy);
+    }
+}
+exports.MissingCachePartitionError = MissingCachePartitionError;
+//# sourceMappingURL=missing-partition.error.js.map

package/dist/errors/missing-partition.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-partition.error.js","sourceRoot":"","sources":["../../src/errors/missing-partition.error.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AAEtE,gDAA8D;AAK9D;;;;;;;;;GASG;AACH,MAAa,0BAA2B,SAAQ,4BAA8C;IAC1E,IAAI,GAAG,4BAA4B,CAAC;IAEtD,YACE,WAAmB,EACnB,SAAkC,EAClC,MAAc;QAEd,KAAK,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IACjD,CAAC;CACF;AAVD,gEAUC"}

package/dist/helpers/cache-factory.d.ts

@@ -0,0 +1,39 @@
+import { type Cache } from 'cache-manager';
+import { Keyv } from 'keyv';
+import type { CacheModuleOptions, CacheStoreConfig } from '../interfaces/cache-options.interface';
+/**
+ * Build a single package-owned `Keyv` instance from a declarative store
+ * configuration. Package-owned stores enable `throwOnErrors` so
+ * {@link CacheBehavior} can apply its own `failOpen` / fail-closed policy rather
+ * than having Keyv silently consume backend failures first.
+ */
+export declare function buildKeyv(config: CacheStoreConfig): Keyv;
+/**
+ * Resolve the {@link CacheModuleOptions} into a ready-to-use `cache-manager`
+ * {@link Cache}. A pre-built `cache` wins, followed by pre-built `stores`,
+ * followed by declarative `store` configuration, falling back to an in-memory
+ * store when nothing is provided.
+ *
+ * Package-created stores use `throwOnErrors: true` so cache failures reach
+ * `CacheBehavior` and its configured failure policy. Caller-owned `cache` and
+ * `stores` are **not mutated**: if an application intentionally shares a Keyv
+ * instance with another subsystem, this package must not change that object's
+ * error semantics globally.
+ *
+ * @example Fully package-owned Redis cache
+ * ```ts
+ * CacheModule.forRoot({
+ *   store: { type: 'redis', url: process.env.REDIS_URL! },
+ *   defaults: { failOpen: true },
+ * });
+ * ```
+ *
+ * @example Caller-owned shared store — configuration remains caller-controlled
+ * ```ts
+ * const shared = new Keyv({ store: sharedRedis, throwOnErrors: false });
+ * CacheModule.forRoot({ stores: [shared] });
+ * // buildCache() will not mutate shared.throwOnErrors.
+ * ```
+ */
+export declare function buildCache(options: CacheModuleOptions): Cache;
+//# sourceMappingURL=cache-factory.d.ts.map

package/dist/helpers/cache-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-factory.d.ts","sourceRoot":"","sources":["../../src/helpers/cache-factory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,KAAK,EAAe,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,IAAI,EAAyB,MAAM,MAAM,CAAC;AACnD,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAEjB,MAAM,uCAAuC,CAAC;AAmG/C;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAexD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,kBAAkB,GAAG,KAAK,CAsB7D"}

package/dist/helpers/cache-factory.js

@@ -0,0 +1,152 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildKeyv = buildKeyv;
+exports.buildCache = buildCache;
+const cache_manager_1 = require("cache-manager");
+const keyv_1 = require("keyv");
+/** Maps declarative store types to their optional `@keyv/*` adapter package. */
+const ADAPTER_PACKAGES = {
+    redis: '@keyv/redis',
+    memcache: '@keyv/memcache',
+    sqlite: '@keyv/sqlite',
+    postgres: '@keyv/postgres',
+};
+/**
+ * Whether the requested adapter package itself could not be resolved.
+ *
+ * Only a resolution failure *for that exact package* counts. A `MODULE_NOT_FOUND`
+ * naming some other module means the adapter is installed but one of its own
+ * dependencies is not, and a native binding failure means it is installed but
+ * did not build.
+ */
+function isRequestedModuleMissing(error, pkg) {
+    if (!(error instanceof Error))
+        return false;
+    if (error.code !== 'MODULE_NOT_FOUND') {
+        return false;
+    }
+    return (error.message.includes(`Cannot find module '${pkg}'`) ||
+        error.message.includes(`Cannot find module "${pkg}"`));
+}
+/** Whether the adapter is present but its native binary is missing or unusable. */
+function isNativeBindingFailure(error) {
+    if (!(error instanceof Error))
+        return false;
+    return (error.message.includes('bindings file') ||
+        error.message.includes('was compiled against a different Node.js version') ||
+        error.message.includes('invalid ELF header'));
+}
+/**
+ * Lazily resolve an optional `@keyv/*` adapter. The adapters are declared as
+ * optional peer dependencies, so they are only required when the matching store
+ * type is actually requested.
+ *
+ * Each failure keeps its own diagnosis, and every wrapper preserves `cause`:
+ *
+ * - the package cannot be resolved  → install it;
+ * - the package loaded but its native binary did not → rebuild it;
+ * - anything else → rethrown untouched, so the real root cause survives.
+ */
+function requireAdapter(pkg) {
+    let mod;
+    try {
+        mod = require(pkg);
+    }
+    catch (error) {
+        if (isRequestedModuleMissing(error, pkg)) {
+            throw new Error(`[pipeline-cache] The optional '${pkg}' package is required for this store type. Install it with: pnpm add ${pkg}`, { cause: error });
+        }
+        if (isNativeBindingFailure(error)) {
+            throw new Error(`[pipeline-cache] '${pkg}' is installed but its native binding could not be loaded. ` +
+                `Rebuild it for this Node.js version (for example: pnpm rebuild ${pkg}); reinstalling the package alone will not help.`, { cause: error });
+        }
+        // An installed adapter that failed for any other reason — a missing
+        // transitive dependency, a broken export, an initialization error. Its own
+        // message is the accurate one.
+        throw error;
+    }
+    return (mod.default ??
+        mod);
+}
+/** Construct the backing `Keyv` store adapter for a declarative config. */
+function createAdapterStore(config) {
+    const { type, url, options } = config;
+    const Adapter = requireAdapter(ADAPTER_PACKAGES[type]);
+    if (type === 'postgres') {
+        return new Adapter({ uri: url, ...options });
+    }
+    return new Adapter(url, options);
+}
+/**
+ * Build a single package-owned `Keyv` instance from a declarative store
+ * configuration. Package-owned stores enable `throwOnErrors` so
+ * {@link CacheBehavior} can apply its own `failOpen` / fail-closed policy rather
+ * than having Keyv silently consume backend failures first.
+ */
+function buildKeyv(config) {
+    if (config.type === 'memory') {
+        return new keyv_1.Keyv({
+            namespace: config.namespace,
+            ttl: config.ttl,
+            throwOnErrors: true,
+        });
+    }
+    return new keyv_1.Keyv({
+        store: createAdapterStore(config),
+        namespace: config.namespace,
+        ttl: config.ttl,
+        throwOnErrors: true,
+    });
+}
+/**
+ * Resolve the {@link CacheModuleOptions} into a ready-to-use `cache-manager`
+ * {@link Cache}. A pre-built `cache` wins, followed by pre-built `stores`,
+ * followed by declarative `store` configuration, falling back to an in-memory
+ * store when nothing is provided.
+ *
+ * Package-created stores use `throwOnErrors: true` so cache failures reach
+ * `CacheBehavior` and its configured failure policy. Caller-owned `cache` and
+ * `stores` are **not mutated**: if an application intentionally shares a Keyv
+ * instance with another subsystem, this package must not change that object's
+ * error semantics globally.
+ *
+ * @example Fully package-owned Redis cache
+ * ```ts
+ * CacheModule.forRoot({
+ *   store: { type: 'redis', url: process.env.REDIS_URL! },
+ *   defaults: { failOpen: true },
+ * });
+ * ```
+ *
+ * @example Caller-owned shared store — configuration remains caller-controlled
+ * ```ts
+ * const shared = new Keyv({ store: sharedRedis, throwOnErrors: false });
+ * CacheModule.forRoot({ stores: [shared] });
+ * // buildCache() will not mutate shared.throwOnErrors.
+ * ```
+ */
+function buildCache(options) {
+    if (options.cache) {
+        return options.cache;
+    }
+    let stores;
+    if (options.stores && options.stores.length > 0) {
+        stores = options.stores;
+    }
+    else if (options.store) {
+        const configs = Array.isArray(options.store)
+            ? options.store
+            : [options.store];
+        stores = configs.map(buildKeyv);
+    }
+    else {
+        stores = [new keyv_1.Keyv({ throwOnErrors: true })];
+    }
+    return (0, cache_manager_1.createCache)({
+        stores,
+        ttl: options.ttl,
+        nonBlocking: options.nonBlocking,
+    });
+}
+//# sourceMappingURL=cache-factory.js.map

package/dist/helpers/cache-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-factory.js","sourceRoot":"","sources":["../../src/helpers/cache-factory.ts"],"names":[],"mappings":";AAAA,sEAAsE;;AAiHtE,8BAeC;AA6BD,gCAsBC;AAjLD,iDAAwD;AACxD,+BAAmD;AASnD,gFAAgF;AAChF,MAAM,gBAAgB,GAAsD;IAC1E,KAAK,EAAE,aAAa;IACpB,QAAQ,EAAE,gBAAgB;IAC1B,MAAM,EAAE,cAAc;IACtB,QAAQ,EAAE,gBAAgB;CAC3B,CAAC;AAEF;;;;;;;GAOG;AACH,SAAS,wBAAwB,CAAC,KAAc,EAAE,GAAW;IAC3D,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAK,KAAoC,CAAC,IAAI,KAAK,kBAAkB,EAAE,CAAC;QACtE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,CACL,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,uBAAuB,GAAG,GAAG,CAAC;QACrD,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,uBAAuB,GAAG,GAAG,CAAC,CACtD,CAAC;AACJ,CAAC;AAED,mFAAmF;AACnF,SAAS,sBAAsB,CAAC,KAAc;IAC5C,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,CACL,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;QACvC,KAAK,CAAC,OAAO,CAAC,QAAQ,CACpB,kDAAkD,CACnD;QACD,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAC7C,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,cAAc,CAAC,GAAW;IACjC,IAAI,GAA0D,CAAC;IAC/D,IAAI,CAAC;QACH,GAAG,GAAG,OAAO,CAAC,GAAG,CAA0D,CAAC;IAC9E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,wBAAwB,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,KAAK,CACb,kCAAkC,GAAG,wEAAwE,GAAG,EAAE,EAClH,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;QAED,IAAI,sBAAsB,CAAC,KAAK,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CACb,qBAAqB,GAAG,6DAA6D;gBACnF,kEAAkE,GAAG,kDAAkD,EACzH,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;QAED,oEAAoE;QACpE,2EAA2E;QAC3E,+BAA+B;QAC/B,MAAM,KAAK,CAAC;IACd,CAAC;IACD,OAAO,CACJ,GAAwC,CAAC,OAAO;QAChD,GAA0B,CAC5B,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,SAAS,kBAAkB,CAAC,MAAwB;IAClD,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IACtC,MAAM,OAAO,GAAG,cAAc,CAC5B,gBAAgB,CAAC,IAAyC,CAAC,CAC5D,CAAC;IAEF,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QACxB,OAAO,IAAI,OAAO,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AACnC,CAAC;AAED;;;;;GAKG;AACH,SAAgB,SAAS,CAAC,MAAwB;IAChD,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,IAAI,WAAI,CAAC;YACd,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,GAAG,EAAE,MAAM,CAAC,GAAG;YACf,aAAa,EAAE,IAAI;SACpB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,IAAI,WAAI,CAAC;QACd,KAAK,EAAE,kBAAkB,CAAC,MAAM,CAAC;QACjC,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,aAAa,EAAE,IAAI;KACpB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,SAAgB,UAAU,CAAC,OAA2B;IACpD,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO,OAAO,CAAC,KAAK,CAAC;IACvB,CAAC;IAED,IAAI,MAAc,CAAC;IACnB,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChD,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC1B,CAAC;SAAM,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;YAC1C,CAAC,CAAC,OAAO,CAAC,KAAK;YACf,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACpB,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,CAAC,IAAI,WAAI,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,IAAA,2BAAW,EAAC;QACjB,MAAM;QACN,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,WAAW,EAAE,OAAO,CAAC,WAAW;KACjC,CAAC,CAAC;AACL,CAAC"}

package/dist/helpers/cache-key.d.ts

@@ -0,0 +1,79 @@
+import { type IPipelineContext, type TenantPartitionOptions } from '@nestjs-pipeline/core';
+import type { CacheKeyFactory } from '../interfaces/cache-options.interface';
+/** Options for {@link createPartitionedCacheKeyFactory}. */
+export interface PartitionedCacheKeyOptions extends TenantPartitionOptions {
+    /**
+     * Resolves the principal the response is scoped to.
+     *
+     * Required whenever the handler performs entity-level authorization or field
+     * filtering, because a cache hit skips the handler entirely — and therefore
+     * skips those checks.
+     */
+    principal: (context: IPipelineContext) => string | undefined;
+    /**
+     * Resolves a fingerprint of the caller's permission scope — a role-set hash or
+     * a capability version.
+     *
+     * Without it, a principal whose roles change keeps reading responses computed
+     * under the old permissions until the entry expires.
+     */
+    scope?: (context: IPipelineContext) => string | undefined;
+    /**
+     * Whether a missing principal is an error.
+     *
+     * Set to `false` only for genuinely public, identical-for-everyone responses.
+     *
+     * @default true
+     */
+    requirePrincipal?: boolean;
+    /**
+     * Whether a missing authorization scope is an error rather than an omitted segment.
+     *
+     * Set to `false` only when responses do not depend on the caller's permissions;
+     * `scope` may then be omitted.
+     *
+     * @default true
+     */
+    requireScope?: boolean;
+}
+/**
+ * Builds a cache key that partitions every dimension capable of changing an
+ * authorized response.
+ *
+ * The key includes tenant, principal, optional permission scope, request type,
+ * and a SHA-256 digest of the request payload. This keeps raw request data out
+ * of cache key listings while preventing authorized responses from being shared
+ * across callers with different security context.
+ *
+ * Use this helper when a cache hit can bypass authorization or response
+ * filtering performed inside the handler.
+ *
+ * @param options - Resolvers and fail-closed requirements for key partitioning.
+ * @returns A `CacheKeyFactory` suitable for `CacheBehaviorOptions.key`.
+ * @throws {TypeError} When `requireScope` is not `false` and no `scope` resolver is given.
+ * @throws {MissingCachePartitionError} (from the returned factory) When a required
+ *   tenant, principal or scope is absent.
+ *
+ * @example Per principal, tenant-aware, invalidated when roles change
+ * ```ts
+ * @UsePipeline([CacheBehavior, {
+ *   key: createPartitionedCacheKeyFactory({
+ *     principal: (ctx) => ctx.items.get('currentUserId') as string | undefined,
+ *     scope: (ctx) => ctx.items.get('capabilityVersion') as string | undefined,
+ *   }),
+ * }])
+ * export class GetUsersHandler {}
+ * ```
+ *
+ * @example Public reference data, identical for every caller
+ * ```ts
+ * createPartitionedCacheKeyFactory({
+ *   principal: () => 'public',
+ *   requirePrincipal: false,
+ *   requireTenant: false,
+ *   requireScope: false,
+ * });
+ * ```
+ */
+export declare function createPartitionedCacheKeyFactory(options: PartitionedCacheKeyOptions): CacheKeyFactory;
+//# sourceMappingURL=cache-key.d.ts.map

package/dist/helpers/cache-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-key.d.ts","sourceRoot":"","sources":["../../src/helpers/cache-key.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAE5B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAK7E,4DAA4D;AAC5D,MAAM,WAAW,0BAA2B,SAAQ,sBAAsB;IACxE;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,CAAC;IAE7D;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,CAAC;IAE1D;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,0BAA0B,GAClC,eAAe,CAuDjB"}

package/dist/helpers/cache-key.js

@@ -0,0 +1,92 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPartitionedCacheKeyFactory = createPartitionedCacheKeyFactory;
+const node_crypto_1 = require("node:crypto");
+const safe_stringify_1 = require("@cqrs-ddd/safe-stringify");
+const core_1 = require("@nestjs-pipeline/core");
+const missing_partition_error_1 = require("../errors/missing-partition.error");
+/** Key format version. Bump to make a format change produce a cold cache. */
+const KEY_VERSION = 'v3';
+/** Deterministic digest of the request payload, so secrets stay out of key listings. */
+function digestRequest(request) {
+    return (0, node_crypto_1.createHash)('sha256').update((0, safe_stringify_1.stableStringify)(request)).digest('hex');
+}
+/**
+ * Builds a cache key that partitions every dimension capable of changing an
+ * authorized response.
+ *
+ * The key includes tenant, principal, optional permission scope, request type,
+ * and a SHA-256 digest of the request payload. This keeps raw request data out
+ * of cache key listings while preventing authorized responses from being shared
+ * across callers with different security context.
+ *
+ * Use this helper when a cache hit can bypass authorization or response
+ * filtering performed inside the handler.
+ *
+ * @param options - Resolvers and fail-closed requirements for key partitioning.
+ * @returns A `CacheKeyFactory` suitable for `CacheBehaviorOptions.key`.
+ * @throws {TypeError} When `requireScope` is not `false` and no `scope` resolver is given.
+ * @throws {MissingCachePartitionError} (from the returned factory) When a required
+ *   tenant, principal or scope is absent.
+ *
+ * @example Per principal, tenant-aware, invalidated when roles change
+ * ```ts
+ * @UsePipeline([CacheBehavior, {
+ *   key: createPartitionedCacheKeyFactory({
+ *     principal: (ctx) => ctx.items.get('currentUserId') as string | undefined,
+ *     scope: (ctx) => ctx.items.get('capabilityVersion') as string | undefined,
+ *   }),
+ * }])
+ * export class GetUsersHandler {}
+ * ```
+ *
+ * @example Public reference data, identical for every caller
+ * ```ts
+ * createPartitionedCacheKeyFactory({
+ *   principal: () => 'public',
+ *   requirePrincipal: false,
+ *   requireTenant: false,
+ *   requireScope: false,
+ * });
+ * ```
+ */
+function createPartitionedCacheKeyFactory(options) {
+    const requirePrincipal = options.requirePrincipal ?? true;
+    const requireScope = options.requireScope ?? true;
+    if (requireScope && !options.scope) {
+        throw new TypeError('createPartitionedCacheKeyFactory requires a `scope` resolver: a cache hit ' +
+            'skips the handler, so a response computed under revoked permissions would ' +
+            'keep being served. Pass requireScope: false when responses do not depend ' +
+            "on the caller's permissions.");
+    }
+    return (context) => {
+        const tenant = (0, core_1.tenantSegments)(context, options, missing_partition_error_1.MissingCachePartitionError);
+        const resolvedPrincipal = options.principal(context);
+        const principal = typeof resolvedPrincipal === 'string' ? resolvedPrincipal.trim() : '';
+        if (requirePrincipal && !principal) {
+            throw new missing_partition_error_1.MissingCachePartitionError(context.requestName, 'principal', 'A cache hit skips the handler and therefore its entity-level ' +
+                'authorization. Return the authenticated principal, or pass ' +
+                'requirePrincipal: false for a genuinely public response.');
+        }
+        const resolvedScope = options.scope?.(context);
+        const scope = typeof resolvedScope === 'string' && resolvedScope.trim()
+            ? resolvedScope.trim()
+            : undefined;
+        if (requireScope && !scope) {
+            throw new missing_partition_error_1.MissingCachePartitionError(context.requestName, 'scope', 'A cache hit skips the handler and therefore its entity-level ' +
+                'authorization. Return the authorization scope, or pass ' +
+                'requireScope: false when responses are scope-independent.');
+        }
+        return (0, safe_stringify_1.joinKeySegments)([
+            'cache',
+            KEY_VERSION,
+            ...tenant,
+            principal || undefined,
+            scope,
+            context.requestName,
+            digestRequest(context.request),
+        ]);
+    };
+}
+//# sourceMappingURL=cache-key.js.map

package/dist/helpers/cache-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-key.js","sourceRoot":"","sources":["../../src/helpers/cache-key.ts"],"names":[],"mappings":";AAAA,sEAAsE;;AAmGtE,4EAyDC;AA1JD,6CAAyC;AACzC,6DAA4E;AAC5E,gDAI+B;AAC/B,+EAA+E;AAG/E,6EAA6E;AAC7E,MAAM,WAAW,GAAG,IAAI,CAAC;AA0CzB,wFAAwF;AACxF,SAAS,aAAa,CAAC,OAAgB;IACrC,OAAO,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAA,gCAAe,EAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,SAAgB,gCAAgC,CAC9C,OAAmC;IAEnC,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,IAAI,CAAC;IAC1D,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,IAAI,CAAC;IAClD,IAAI,YAAY,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACnC,MAAM,IAAI,SAAS,CACjB,4EAA4E;YAC1E,4EAA4E;YAC5E,2EAA2E;YAC3E,8BAA8B,CACjC,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,OAAO,EAAE,EAAE;QACjB,MAAM,MAAM,GAAG,IAAA,qBAAc,EAAC,OAAO,EAAE,OAAO,EAAE,oDAA0B,CAAC,CAAC;QAE5E,MAAM,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACrD,MAAM,SAAS,GACb,OAAO,iBAAiB,KAAK,QAAQ,CAAC,CAAC,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAExE,IAAI,gBAAgB,IAAI,CAAC,SAAS,EAAE,CAAC;YACnC,MAAM,IAAI,oDAA0B,CAClC,OAAO,CAAC,WAAW,EACnB,WAAW,EACX,+DAA+D;gBAC7D,6DAA6D;gBAC7D,0DAA0D,CAC7D,CAAC;QACJ,CAAC;QAED,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,CAAC;QAC/C,MAAM,KAAK,GACT,OAAO,aAAa,KAAK,QAAQ,IAAI,aAAa,CAAC,IAAI,EAAE;YACvD,CAAC,CAAC,aAAa,CAAC,IAAI,EAAE;YACtB,CAAC,CAAC,SAAS,CAAC;QAEhB,IAAI,YAAY,IAAI,CAAC,KAAK,EAAE,CAAC;YAC3B,MAAM,IAAI,oDAA0B,CAClC,OAAO,CAAC,WAAW,EACnB,OAAO,EACP,+DAA+D;gBAC7D,yDAAyD;gBACzD,2DAA2D,CAC9D,CAAC;QACJ,CAAC;QAED,OAAO,IAAA,gCAAe,EAAC;YACrB,OAAO;YACP,WAAW;YACX,GAAG,MAAM;YACT,SAAS,IAAI,SAAS;YACtB,KAAK;YACL,OAAO,CAAC,WAAW;YACnB,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC;SAC/B,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/helpers/cache.intent.d.ts

@@ -0,0 +1,26 @@
+import type { PipelineBehaviorTuple } from '@nestjs-pipeline/core';
+import { CacheBehavior } from '../cache.behavior';
+import type { CacheBehaviorOptions } from '../interfaces/cache-options.interface';
+export type CacheIntentOptions = Omit<CacheBehaviorOptions, 'key'> & ({
+    key: NonNullable<CacheBehaviorOptions['key']>;
+    inheritModuleKey?: never;
+} | {
+    inheritModuleKey: true;
+    key?: never;
+});
+/**
+ * Returns a cache behavior entry for `@UsePipeline`.
+ * @param options A key factory and cache options, or `inheritModuleKey: true`
+ * when the module supplies the key factory. The inheritance marker is not
+ * forwarded to the behavior and does not validate module configuration.
+ * @returns The behavior class and options tuple.
+ * Keys for authorized responses must separate tenant, principal and permission
+ * scope; prefer `createPartitionedCacheKeyFactory` for those responses.
+ * @example
+ * ```ts
+ * @UsePipeline(cache({ key: userCacheKey, ttl: 30_000 }))
+ * @UsePipeline(cache({ inheritModuleKey: true, ttl: 30_000 }))
+ * ```
+ */
+export declare function cache(options: CacheIntentOptions): PipelineBehaviorTuple<CacheBehavior, CacheBehaviorOptions>;
+//# sourceMappingURL=cache.intent.d.ts.map

package/dist/helpers/cache.intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.intent.d.ts","sourceRoot":"","sources":["../../src/helpers/cache.intent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAElF,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,oBAAoB,EAAE,KAAK,CAAC,GAChE,CACI;IACE,GAAG,EAAE,WAAW,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9C,gBAAgB,CAAC,EAAE,KAAK,CAAC;CAC1B,GACD;IAAE,gBAAgB,EAAE,IAAI,CAAC;IAAC,GAAG,CAAC,EAAE,KAAK,CAAA;CAAE,CAC1C,CAAC;AAEJ;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CACnB,OAAO,EAAE,kBAAkB,GAC1B,qBAAqB,CAAC,aAAa,EAAE,oBAAoB,CAAC,CAG5D"}

package/dist/helpers/cache.intent.js

@@ -0,0 +1,24 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cache = cache;
+const cache_behavior_1 = require("../cache.behavior");
+/**
+ * Returns a cache behavior entry for `@UsePipeline`.
+ * @param options A key factory and cache options, or `inheritModuleKey: true`
+ * when the module supplies the key factory. The inheritance marker is not
+ * forwarded to the behavior and does not validate module configuration.
+ * @returns The behavior class and options tuple.
+ * Keys for authorized responses must separate tenant, principal and permission
+ * scope; prefer `createPartitionedCacheKeyFactory` for those responses.
+ * @example
+ * ```ts
+ * @UsePipeline(cache({ key: userCacheKey, ttl: 30_000 }))
+ * @UsePipeline(cache({ inheritModuleKey: true, ttl: 30_000 }))
+ * ```
+ */
+function cache(options) {
+    const { inheritModuleKey: _inheritModuleKey, ...behaviorOptions } = options;
+    return [cache_behavior_1.CacheBehavior, behaviorOptions];
+}
+//# sourceMappingURL=cache.intent.js.map

package/dist/helpers/cache.intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.intent.js","sourceRoot":"","sources":["../../src/helpers/cache.intent.ts"],"names":[],"mappings":";AAAA,sEAAsE;;AA6BtE,sBAKC;AA/BD,sDAAkD;AAYlD;;;;;;;;;;;;;GAaG;AACH,SAAgB,KAAK,CACnB,OAA2B;IAE3B,MAAM,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,GAAG,eAAe,EAAE,GAAG,OAAO,CAAC;IAC5E,OAAO,CAAC,8BAAa,EAAE,eAAe,CAAC,CAAC;AAC1C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { CacheManagerAdapter, type IPipelineCache, } from './adapters/cache-manager.adapter';
+export { CACHE_HIT_ITEM, CACHE_HIT_ITEM_TOKEN, CACHE_KEY_ITEM, CACHE_KEY_ITEM_TOKEN, CacheBehavior, } from './cache.behavior';
+export { CacheModule } from './cache.module';
+export { CACHE_DEFAULT_OPTIONS, PIPELINE_CACHE } from './constants/tokens';
+export { type CachePartitionDimension, MissingCachePartitionError, } from './errors/missing-partition.error';
+export { type CacheIntentOptions, cache, } from './helpers/cache.intent';
+export { buildCache, buildKeyv } from './helpers/cache-factory';
+export { createPartitionedCacheKeyFactory, type PartitionedCacheKeyOptions, } from './helpers/cache-key';
+export type { CacheBehaviorOptions, CacheCondition, CacheKeyFactory, CacheModuleAsyncOptions, CacheModuleOptions, CacheStoreConfig, CacheStoreType, } from './interfaces/cache-options.interface';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,27 @@
+"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;
+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");
+Object.defineProperty(exports, "CACHE_HIT_ITEM", { enumerable: true, get: function () { return cache_behavior_1.CACHE_HIT_ITEM; } });
+Object.defineProperty(exports, "CACHE_HIT_ITEM_TOKEN", { enumerable: true, get: function () { return cache_behavior_1.CACHE_HIT_ITEM_TOKEN; } });
+Object.defineProperty(exports, "CACHE_KEY_ITEM", { enumerable: true, get: function () { return cache_behavior_1.CACHE_KEY_ITEM; } });
+Object.defineProperty(exports, "CACHE_KEY_ITEM_TOKEN", { enumerable: true, get: function () { return cache_behavior_1.CACHE_KEY_ITEM_TOKEN; } });
+Object.defineProperty(exports, "CacheBehavior", { enumerable: true, get: function () { return cache_behavior_1.CacheBehavior; } });
+var cache_module_1 = require("./cache.module");
+Object.defineProperty(exports, "CacheModule", { enumerable: true, get: function () { return cache_module_1.CacheModule; } });
+var tokens_1 = require("./constants/tokens");
+Object.defineProperty(exports, "CACHE_DEFAULT_OPTIONS", { enumerable: true, get: function () { return tokens_1.CACHE_DEFAULT_OPTIONS; } });
+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 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");
+Object.defineProperty(exports, "buildCache", { enumerable: true, get: function () { return cache_factory_1.buildCache; } });
+Object.defineProperty(exports, "buildKeyv", { enumerable: true, get: function () { return cache_factory_1.buildKeyv; } });
+var cache_key_1 = require("./helpers/cache-key");
+Object.defineProperty(exports, "createPartitionedCacheKeyFactory", { enumerable: true, get: function () { return cache_key_1.createPartitionedCacheKeyFactory; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}