@cqrs-ddd/pipeline-cache 0.5.0

package/dist/helpers/cache-factory.js

@@ -0,0 +1,147 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { createRequire } from 'node:module';
+import { createCache } from 'cache-manager';
+import { Keyv } from 'keyv';
+const load = createRequire(import.meta.url);
+/** 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 = load(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.
+ */
+export function buildKeyv(config) {
+    if (config.type === 'memory') {
+        return new Keyv({
+            namespace: config.namespace,
+            ttl: config.ttl,
+            throwOnErrors: true,
+        });
+    }
+    return new Keyv({
+        store: createAdapterStore(config),
+        namespace: config.namespace,
+        ttl: config.ttl,
+        throwOnErrors: true,
+    });
+}
+/**
+ * Resolve the {@link BuildCacheOptions} 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
+ * const cache = buildCache({ store: { type: 'redis', url: redisUrl } });
+ * ```
+ *
+ * @example Caller-owned shared store — configuration remains caller-controlled
+ * ```ts
+ * const shared = new Keyv({ store: sharedRedis, throwOnErrors: false });
+ * const cache = buildCache({ stores: [shared] });
+ * // buildCache() will not mutate shared.throwOnErrors.
+ * ```
+ */
+export 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({ throwOnErrors: true })];
+    }
+    return 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":"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"}

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

@@ -0,0 +1,81 @@
+import { type IPipelineContext, type TenantPartitionOptions } from '@cqrs-ddd/pipeline';
+import type { CacheKeyFactory } from '../interfaces/cache-options.interface.js';
+/** 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
+ * class GetUsersHandler {
+ *   @pipeline.wrap({ kind: 'query' }, [CacheBehavior, {
+ *     key: createPartitionedCacheKeyFactory({
+ *       principal: (ctx) => ctx.items.get('currentUserId') as string | undefined,
+ *       scope: (ctx) => ctx.items.get('capabilityVersion') as string | undefined,
+ *     }),
+ *   }])
+ *   async handle(query: GetUsersQuery) {}
+ * }
+ * ```
+ *
+ * @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":"AAGA,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAE5B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAKhF,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,0BAA0B,GAClC,eAAe,CAuDjB"}

package/dist/helpers/cache-key.js

@@ -0,0 +1,91 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { createHash } from 'node:crypto';
+import { tenantSegments, } from '@cqrs-ddd/pipeline';
+import { joinKeySegments, stableStringify } from '@cqrs-ddd/safe-stringify';
+import { MissingCachePartitionError } from '../errors/missing-partition.error.js';
+/** 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 createHash('sha256').update(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
+ * class GetUsersHandler {
+ *   @pipeline.wrap({ kind: 'query' }, [CacheBehavior, {
+ *     key: createPartitionedCacheKeyFactory({
+ *       principal: (ctx) => ctx.items.get('currentUserId') as string | undefined,
+ *       scope: (ctx) => ctx.items.get('capabilityVersion') as string | undefined,
+ *     }),
+ *   }])
+ *   async handle(query: GetUsersQuery) {}
+ * }
+ * ```
+ *
+ * @example Public reference data, identical for every caller
+ * ```ts
+ * createPartitionedCacheKeyFactory({
+ *   principal: () => 'public',
+ *   requirePrincipal: false,
+ *   requireTenant: false,
+ *   requireScope: false,
+ * });
+ * ```
+ */
+export 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 = tenantSegments(context, options, MissingCachePartitionError);
+        const resolvedPrincipal = options.principal(context);
+        const principal = typeof resolvedPrincipal === 'string' ? resolvedPrincipal.trim() : '';
+        if (requirePrincipal && !principal) {
+            throw new 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 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 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;AAEtE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAGL,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAGlF,6EAA6E;AAC7E,MAAM,WAAW,GAAG,IAAI,CAAC;AA0CzB,wFAAwF;AACxF,SAAS,aAAa,CAAC,OAAgB;IACrC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,UAAU,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,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,0BAA0B,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,0BAA0B,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,0BAA0B,CAClC,OAAO,CAAC,WAAW,EACnB,OAAO,EACP,+DAA+D;gBAC7D,yDAAyD;gBACzD,2DAA2D,CAC9D,CAAC;QACJ,CAAC;QAED,OAAO,eAAe,CAAC;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,31 @@
+import type { PipelineBehaviorTuple } from '@cqrs-ddd/pipeline';
+import { CacheBehavior } from '../cache.behavior.js';
+import type { CacheBehaviorOptions } from '../interfaces/cache-options.interface.js';
+export type CacheIntentOptions = Omit<CacheBehaviorOptions, 'key'> & ({
+    key: NonNullable<CacheBehaviorOptions['key']>;
+    inheritModuleKey?: never;
+} | {
+    inheritModuleKey: true;
+    key?: never;
+});
+/**
+ * Returns a cache behavior entry for `pipeline.wrap()` or `createPipeline({ globalBehaviors })`.
+ * @param options A key factory and cache options, or `inheritModuleKey: true`
+ * when the behavior's constructor defaults supply 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
+ * export const getUsers = pipeline.wrap(
+ *   { name: 'getUsers', kind: 'query' },
+ *   cache({ key: userCacheKey, ttl: 30_000 }),
+ * )(loadUsers);
+ *
+ * // The key factory comes from the CacheBehavior constructor defaults.
+ * const entry = 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,oBAAoB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AAErF,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;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,KAAK,CACnB,OAAO,EAAE,kBAAkB,GAC1B,qBAAqB,CAAC,aAAa,EAAE,oBAAoB,CAAC,CAG5D"}

package/dist/helpers/cache.intent.js

@@ -0,0 +1,26 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { CacheBehavior } from '../cache.behavior.js';
+/**
+ * Returns a cache behavior entry for `pipeline.wrap()` or `createPipeline({ globalBehaviors })`.
+ * @param options A key factory and cache options, or `inheritModuleKey: true`
+ * when the behavior's constructor defaults supply 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
+ * export const getUsers = pipeline.wrap(
+ *   { name: 'getUsers', kind: 'query' },
+ *   cache({ key: userCacheKey, ttl: 30_000 }),
+ * )(loadUsers);
+ *
+ * // The key factory comes from the CacheBehavior constructor defaults.
+ * const entry = cache({ inheritModuleKey: true, ttl: 30_000 });
+ * ```
+ */
+export function cache(options) {
+    const { inheritModuleKey: _inheritModuleKey, ...behaviorOptions } = options;
+    return [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;AAGtE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAYrD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,KAAK,CACnB,OAA2B;IAE3B,MAAM,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,GAAG,eAAe,EAAE,GAAG,OAAO,CAAC;IAC5E,OAAO,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;AAC1C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { CacheManagerAdapter, type IPipelineCache, } from './adapters/cache-manager.adapter.js';
+export { CACHE_HIT_ITEM, CACHE_HIT_ITEM_TOKEN, CACHE_KEY_ITEM, CACHE_KEY_ITEM_TOKEN, CacheBehavior, } from './cache.behavior.js';
+export { type CachePartitionDimension, MissingCachePartitionError, } from './errors/missing-partition.error.js';
+export { buildCacheAttributes } from './helpers/build-attributes.js';
+export { type CacheIntentOptions, cache, } from './helpers/cache.intent.js';
+export { buildCache, buildKeyv } from './helpers/cache-factory.js';
+export { createPartitionedCacheKeyFactory, type PartitionedCacheKeyOptions, } from './helpers/cache-key.js';
+export type { BuildCacheOptions, CacheBehaviorOptions, CacheCondition, CacheKeyFactory, CacheStoreConfig, CacheStoreType, } from './interfaces/cache-options.interface.js';
+//# 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,qCAAqC,CAAC;AAC7C,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,uBAAuB,EAC5B,0BAA0B,GAC3B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,GACN,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EACL,gCAAgC,EAChC,KAAK,0BAA0B,GAChC,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,cAAc,GACf,MAAM,yCAAyC,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+export { CacheManagerAdapter, } from './adapters/cache-manager.adapter.js';
+export { CACHE_HIT_ITEM, CACHE_HIT_ITEM_TOKEN, CACHE_KEY_ITEM, CACHE_KEY_ITEM_TOKEN, CacheBehavior, } from './cache.behavior.js';
+export { MissingCachePartitionError, } from './errors/missing-partition.error.js';
+export { buildCacheAttributes } from './helpers/build-attributes.js';
+export { cache, } from './helpers/cache.intent.js';
+export { buildCache, buildKeyv } from './helpers/cache-factory.js';
+export { createPartitionedCacheKeyFactory, } from './helpers/cache-key.js';
+//# 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,OAAO,EACL,mBAAmB,GAEpB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,0BAA0B,GAC3B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAEL,KAAK,GACN,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EACL,gCAAgC,GAEjC,MAAM,wBAAwB,CAAC"}

package/dist/interfaces/cache-options.interface.d.ts

@@ -0,0 +1,111 @@
+import type { IPipelineContext } from '@cqrs-ddd/pipeline';
+import type { Cache } from 'cache-manager';
+import type { Keyv } from 'keyv';
+/**
+ * Built-in store backends supported through declarative configuration.
+ *
+ * - `memory`   — in-process `Keyv` map (default, no extra dependency).
+ * - `redis`    — requires the optional `@keyv/redis` package.
+ * - `memcache` — requires the optional `@keyv/memcache` package.
+ * - `sqlite`   — requires the optional `@keyv/sqlite` package.
+ * - `postgres` — requires the optional `@keyv/postgres` package.
+ */
+export type CacheStoreType = 'memory' | 'redis' | 'memcache' | 'sqlite' | 'postgres';
+/**
+ * Declarative description of a single cache store backend. Use this when you
+ * want the module to construct the `Keyv` adapter for you.
+ */
+export interface CacheStoreConfig {
+    /** Which backend to build. */
+    type: CacheStoreType;
+    /**
+     * Connection string / URI for the backend, e.g. `redis://localhost:6379`,
+     * `postgresql://user:pass@localhost:5432/db`, `sqlite://./cache.sqlite`, or
+     * `localhost:11211` for memcache. Ignored for `memory`.
+     */
+    url?: string;
+    /** Key namespace/prefix applied to every entry in this store. */
+    namespace?: string;
+    /** Default time-to-live (milliseconds) for entries written to this store. */
+    ttl?: number;
+    /** Adapter-specific options passed through to the underlying `@keyv/*` package. */
+    options?: Record<string, unknown>;
+}
+/** Factory that derives the cache key for a given pipeline request. */
+export type CacheKeyFactory = (context: IPipelineContext) => string;
+/** Predicate deciding whether a given request should participate in caching. */
+export type CacheCondition = (context: IPipelineContext) => boolean;
+/**
+ * Per-handler caching options, supplied through `pipeline.wrap(options, [CacheBehavior, options])`
+ * and/or as defaults, the second argument of the {@link CacheBehavior} constructor.
+ *
+ * @example
+ * ```ts
+ * class GetUserHandler {
+ *   @pipeline.wrap({ kind: 'query' }, [CacheBehavior, {
+ *     key: createPartitionedCacheKeyFactory({
+ *       principal: (ctx) => ctx.items.get('userId') as string | undefined,
+ *       scope: (ctx) => ctx.items.get('capabilityVersion') as string | undefined,
+ *     }),
+ *     ttl: 60_000,
+ *   }])
+ *   async handle(query: GetUserQuery) {}
+ * }
+ * ```
+ */
+export interface CacheBehaviorOptions {
+    /**
+     * Request kinds eligible for caching. Defaults to `['query']` so that
+     * commands and events bypass the cache automatically.
+     */
+    kinds?: Array<IPipelineContext['requestKind']>;
+    /** Time-to-live (milliseconds) for entries written by this handler. */
+    ttl?: number;
+    /**
+     * Cache-key factory. **Required** when this behavior runs — there is no default.
+     *
+     * A cache hit returns without executing the handler, so the key must partition
+     * every dimension that can change the authorized response: tenant, principal,
+     * permission scope and request payload. Use `createPartitionedCacheKeyFactory`
+     * rather than composing one by hand.
+     */
+    key?: CacheKeyFactory;
+    /** Optional predicate gating whether a given request is cached. */
+    condition?: CacheCondition;
+    /**
+     * When a cache read or write throws, bypass the cache and continue (`true`,
+     * default) or propagate the store error (`false`). A failed read bypasses the
+     * write for that execution. This option does not catch key, condition, or
+     * downstream handler errors.
+     */
+    failOpen?: boolean;
+}
+/**
+ * Options of {@link buildCache}. The store can be provided in
+ * three ways: a pre-built `cache`, pre-built `stores`, or declarative `store`
+ * configuration. When several are given, `cache` takes precedence over
+ * `stores`, which takes precedence over `store`; the others are ignored. An
+ * empty `stores` array counts as absent. When none is supplied an in-memory
+ * store is used.
+ *
+ * @example Redis-backed cache
+ * ```ts
+ * buildCache({
+ *   store: { type: 'redis', url: redisUrl },
+ *   ttl: 30_000,
+ * });
+ * ```
+ */
+export interface BuildCacheOptions {
+    /** Escape hatch: a fully constructed `cache-manager` instance. */
+    cache?: Cache;
+    /** Escape hatch: pre-built `Keyv` stores (tiered, highest priority first). */
+    stores?: Keyv[];
+    /** Declarative store configuration — a single store or a tiered list. */
+    store?: CacheStoreConfig | CacheStoreConfig[];
+    /** Default time-to-live (milliseconds) applied across stores and handlers. */
+    ttl?: number;
+    /** Forwarded to `cache-manager`; optimizes behavior across multiple stores. */
+    nonBlocking?: boolean;
+}
+//# sourceMappingURL=cache-options.interface.d.ts.map

package/dist/interfaces/cache-options.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-options.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/cache-options.interface.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAEjC;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,OAAO,GACP,UAAU,GACV,QAAQ,GACR,UAAU,CAAC;AAEf;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,IAAI,EAAE,cAAc,CAAC;IACrB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,uEAAuE;AACvE,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,MAAM,CAAC;AAEpE,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC;AAEpE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,gBAAgB,CAAC,aAAa,CAAC,CAAC,CAAC;IAC/C,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,eAAe,CAAC;IACtB,mEAAmE;IACnE,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,8EAA8E;IAC9E,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC;IAChB,yEAAyE;IACzE,KAAK,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAAC;IAC9C,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB"}

package/dist/interfaces/cache-options.interface.js

@@ -0,0 +1,3 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+export {};
+//# sourceMappingURL=cache-options.interface.js.map

package/dist/interfaces/cache-options.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-options.interface.js","sourceRoot":"","sources":["../../src/interfaces/cache-options.interface.ts"],"names":[],"mappings":"AAAA,sEAAsE"}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@cqrs-ddd/pipeline-cache",
+  "version": "0.5.0",
+  "description": "Result caching for @cqrs-ddd/pipeline on cache-manager and Keyv stores, with keys partitioned by tenant, principal and permission scope",
+  "author": "Aristotelis",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "keywords": [
+    "pipeline",
+    "cqrs",
+    "cache",
+    "caching",
+    "cache-manager",
+    "keyv",
+    "redis",
+    "behavior"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aristoteliss/ddd-cqrs.git",
+    "directory": "packages/pipeline-cache"
+  },
+  "homepage": "https://aristoteliss.github.io/ddd-cqrs/packages/pipeline-cache/",
+  "bugs": {
+    "url": "https://github.com/aristoteliss/ddd-cqrs/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "COMMERCIAL_LICENSE.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@keyv/memcache": "^2.0.0",
+    "@keyv/postgres": "^2.0.0",
+    "@keyv/redis": "^4.0.0 || ^5.0.0",
+    "@keyv/sqlite": "^4.0.0",
+    "cache-manager": "^7.0.0",
+    "keyv": "^5.0.0",
+    "@cqrs-ddd/pipeline": "^0.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@keyv/memcache": {
+      "optional": true
+    },
+    "@keyv/postgres": {
+      "optional": true
+    },
+    "@keyv/redis": {
+      "optional": true
+    },
+    "@keyv/sqlite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^5.0.3",
+    "cache-manager": "^7.2.9",
+    "keyv": "^5.6.0",
+    "vitest": "^5.0.3",
+    "@cqrs-ddd/pipeline": "0.5.0"
+  },
+  "dependencies": {
+    "@cqrs-ddd/safe-stringify": "^0.5.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "rebuild": "pnpm run clean && pnpm run build",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}