@nestjs-pipeline/cache 0.2.0

package/README.md

@@ -0,0 +1,572 @@
+# @nestjs-pipeline/cache
+
+## Architectural role
+
+This reusable package caches final application query results, including expensive
+aggregations, read models combining repositories and external-service composition.
+It complements repository snapshot/read-through caches; it is not replaced by
+them just because a particular example currently uses repository caching. Choose
+the layer that owns the result and define its dependencies, security scope and
+freshness. Using both layers is optional, and invalidation is not automatically
+shared.
+
+[![npm version](https://img.shields.io/npm/v/@nestjs-pipeline/cache.svg)](https://www.npmjs.com/package/@nestjs-pipeline/cache)
+[![License](https://img.shields.io/npm/l/@nestjs-pipeline/cache.svg)](https://www.npmjs.com/package/@nestjs-pipeline/cache)
+
+Caching behavior for `@nestjs-pipeline/core`, powered by [cache-manager](https://www.npmjs.com/package/cache-manager) v7 on top of [Keyv](https://keyv.org/). Transparently cache query results — declaratively, with zero changes to your handler code — and choose any backend: **memory** (default), **redis**, **memcache**, **sqlite**, or **postgres**.
+
+> **New in 0.2.0:** this is the first published release of the package.
+
+---
+
+## Table of Contents
+
+- [Why](#why)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [1. Register the module](#1-register-the-module)
+  - [2. Attach the behavior](#2-attach-the-behavior)
+  - [3. Configure per handler](#3-configure-per-handler)
+- [Choosing a Store](#choosing-a-store)
+  - [Memory (default)](#memory-default)
+  - [Redis](#redis)
+  - [Memcache](#memcache)
+  - [SQLite](#sqlite)
+  - [Postgres](#postgres)
+  - [Tiered (multi-layer) caches](#tiered-multi-layer-caches)
+  - [Escape hatches](#escape-hatches)
+- [How It Works](#how-it-works)
+  - [What gets cached](#what-gets-cached)
+  - [Cache keys](#cache-keys)
+  - [Tenant partitioning](#tenant-partitioning)
+  - [Options resolution](#options-resolution)
+  - [Context items](#context-items)
+- [Configuration](#configuration)
+- [Behavior Contract & Bootstrap Diagnostics](#behavior-contract--bootstrap-diagnostics)
+- [Custom Logger](#custom-logger)
+- [API Reference](#api-reference)
+- [License](#license)
+
+---
+
+## Why
+
+Read-heavy queries often hit the same data repeatedly. `@nestjs-pipeline/cache` adds a transparent caching layer to your CQRS pipeline without coupling the caching logic to your business code. It is a thin, type-safe behavior over [cache-manager](https://github.com/jaredwray/cacheable) v7 + [Keyv](https://keyv.org/), so you get tiered caches and a consistent interface across every supported backend.
+
+---
+
+## Installation
+
+```bash
+pnpm add @nestjs-pipeline/cache cache-manager keyv
+```
+
+**Peer dependencies:**
+
+```bash
+pnpm add @nestjs-pipeline/core @nestjs/common reflect-metadata
+```
+
+Requires `@nestjs/common` `^11.0.0` and `@nestjs-pipeline/core` `^0.2.0`.
+
+**Optional store adapters** — install only the one(s) you use:
+
+```bash
+pnpm add @keyv/redis      # type: 'redis'
+pnpm add @keyv/memcache   # type: 'memcache'
+pnpm add @keyv/sqlite     # type: 'sqlite'
+pnpm add @keyv/postgres   # type: 'postgres'
+```
+
+> The `memory` store needs no adapter — it ships with Keyv. The other backends are loaded lazily; you only need the matching `@keyv/*` package when you actually select that store type.
+
+---
+
+## Quick Start
+
+### 1. Register the module
+
+```ts
+import { Module } from '@nestjs/common';
+import { PipelineModule } from '@nestjs-pipeline/core';
+import { CacheModule, CacheBehavior } from '@nestjs-pipeline/cache';
+
+@Module({
+  imports: [
+    // In-memory cache with a 30s default TTL
+    CacheModule.forRoot({ ttl: 30_000 }),
+    // Make CacheBehavior available to @UsePipeline/globalBehaviors.
+    PipelineModule.forRoot({ behaviors: [CacheBehavior] }),
+  ],
+})
+export class AppModule {}
+```
+
+The cache is built when the application instantiates its providers, once per
+application. To derive store settings from injected configuration, use
+`forRootAsync`:
+
+```ts
+CacheModule.forRootAsync({
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    store: { type: 'redis', url: config.getOrThrow('REDIS_URL') },
+    ttl: 30_000,
+  }),
+});
+```
+
+A cache built from `store` (or the default memory store) is disconnected on
+application shutdown (`app.close()` or Nest shutdown hooks). A supplied `cache` or
+`stores` belongs to the caller, who closes it.
+
+### 2. Attach the behavior
+
+The `behaviors` option above registers `CacheBehavior` with Nest DI; it does not execute it globally. Attach it per handler with `@UsePipeline`, or put it in `globalBehaviors` if you want it to run for a global scope.
+
+### 3. Configure per handler
+
+This protected-query fragment assumes the pipeline has a tenant (`context.tenantId`,
+see [Tenant partitioning](#tenant-partitioning)) and that an upstream behavior sets
+`currentUserId` and `capabilityVersion` on `context.items` before caching runs.
+The handler still performs entity and field authorization on cache misses.
+
+```ts
+import { QueryHandler, type IQueryHandler } from '@nestjs/cqrs';
+import { UsePipeline } from '@nestjs-pipeline/core';
+import { cache, createPartitionedCacheKeyFactory } from '@nestjs-pipeline/cache';
+
+@QueryHandler(GetUserQuery)
+@UsePipeline(cache({
+  ttl: 60_000,
+  key: createPartitionedCacheKeyFactory({
+    principal: (ctx) => ctx.items.get('currentUserId') as string | undefined,
+    scope: (ctx) => {
+      const scope = ctx.items.get('capabilityVersion');
+      if (typeof scope !== 'string' || !scope.trim()) {
+        throw new Error('Missing capability version');
+      }
+      return scope;
+    },
+  }),
+}))
+export class GetUserHandler implements IQueryHandler<GetUserQuery> {
+  async execute(query: GetUserQuery) {
+    // ...expensive read; result cached for 60s
+  }
+}
+```
+
+> Use `cache({ inheritModuleKey: true })` only when the module supplies the key factory.
+> The raw tuple form `@UsePipeline([CacheBehavior, { ... }])` remains supported as an escape hatch.
+
+---
+
+## Choosing a Store
+
+The backend is selected once, when registering the module. Per-handler options
+(`ttl`, `key`, `condition`, `kinds`) are independent of the store you pick.
+
+### Memory (default)
+
+```ts
+CacheModule.forRoot({ ttl: 30_000 });
+// equivalent to:
+CacheModule.forRoot({ store: { type: 'memory' }, ttl: 30_000 });
+```
+
+### Redis
+
+```ts
+CacheModule.forRoot({
+  store: { type: 'redis', url: 'redis://localhost:6379' },
+  ttl: 60_000,
+});
+```
+
+### Memcache
+
+```ts
+CacheModule.forRoot({
+  store: { type: 'memcache', url: 'localhost:11211' },
+});
+```
+
+### SQLite
+
+```ts
+CacheModule.forRoot({
+  store: { type: 'sqlite', url: 'sqlite://./cache.sqlite' },
+});
+```
+
+### Postgres
+
+```ts
+CacheModule.forRoot({
+  store: {
+    type: 'postgres',
+    url: 'postgresql://user:pass@localhost:5432/db',
+    options: { table: 'cache' },
+  },
+});
+```
+
+### Tiered (multi-layer) caches
+
+Provide an array of stores — they are checked in order (fastest first) and
+writes fan out to every layer:
+
+```ts
+CacheModule.forRoot({
+  store: [
+    { type: 'memory', ttl: 5_000 }, // L1: in-process
+    { type: 'redis', url: 'redis://localhost:6379' }, // L2: shared
+  ],
+});
+```
+
+### Escape hatches
+
+For full control, pass a pre-built `cache-manager` instance or your own `Keyv`
+stores:
+
+```ts
+import { createCache } from 'cache-manager';
+import { Keyv } from 'keyv';
+import KeyvRedis from '@keyv/redis';
+
+// Pre-built Keyv stores
+CacheModule.forRoot({
+  stores: [new Keyv({ store: new KeyvRedis('redis://localhost:6379') })],
+});
+
+// Fully pre-built cache
+CacheModule.forRoot({ cache: createCache({ stores: [new Keyv()] }) });
+```
+
+| Option | Precedence | Description |
+| ------ | ---------- | ----------- |
+| `cache` | 1 (highest) | A ready-made `cache-manager` instance. |
+| `stores` | 2 | Pre-built `Keyv[]` (tiered, highest priority first). |
+| `store` | 3 | Declarative config — a single store or an array. |
+| _(none)_ | 4 (fallback) | In-memory `Keyv`. |
+
+---
+
+## How It Works
+
+### What gets cached
+
+Only **query** requests are cached by default — commands and events always pass
+through untouched. Override this with the `kinds` option. On a cache miss,
+`null` and `undefined` results are not written. A hit returns the value from
+that lookup directly. `CacheBehavior` does not use `cache-manager.wrap()` or
+background refresh because a refresh callback would re-run every behavior and
+side effect nested after the cache behavior.
+
+Cached results are JSON values. On a miss the behavior stores the JSON form of
+the handler result and returns that same form, so a miss and a later hit have
+the same shape: a `Date` is an ISO string and a class instance a plain object on
+both. Return plain JSON data (a snapshot or read model) from cached handlers. A
+result without a JSON form (a `bigint`, a cycle) is returned unchanged, not
+cached, and logged as a warning.
+
+### Store errors
+
+Declaratively created stores use `throwOnErrors: true`. Pre-built `cache` and
+`stores` remain caller-owned and are passed through without changing their error
+settings. The behavior can handle only failures those implementations surface;
+it cannot detect backend errors they swallow.
+
+`CacheBehavior` owns a consistent failure policy independently of the injected
+`cache-manager` or custom cache implementation. By default, `failOpen: true`:
+
+- a thrown cache read is logged, recorded as `cache.hit = false`, and bypasses
+  the cache write for that execution; the handler result still uses the same JSON conversion as a normal miss;
+- a thrown cache write is logged and the successful handler result is returned.
+
+Set `failOpen: false` to log and propagate either store error. This strict mode
+can turn a successful downstream handler execution into a rejected request when
+the subsequent cache write fails, so it is best suited to cases where cache
+availability is part of the operation's contract. Errors from the condition,
+key factory, or downstream handler are always propagated unchanged.
+
+### Cache keys
+
+The helper emits `cache:v3:<tenant>:<principal>:<scope>:<requestName>:<sha256>`,
+with escaped segments and the absent-segment encoding supplied by core
+`joinKeySegments`. Treat the generated key as opaque. Changing from older
+formats causes a cold cache; let old entries expire or remove their namespace.
+
+`key` is **required**. There is deliberately no default.
+
+The previous default embedded `context.correlationId`, which is unique per
+request. That made the cache write an entry for every query and never read one
+back — two extra round-trips and unbounded store growth for a zero percent hit
+rate. It was not an authorization boundary either: a client can send its own
+correlation ID, and nested executions deliberately inherit one. Correlation metadata
+does not establish principal or permission isolation, as correlation IDs may be supplied
+or reused. Cache hits skip the handler, including entity/field checks. For protected
+results, provide an explicit `key` covering tenant, principal type/ID, effective
+permission scope and response dependencies; fail closed if required context is
+missing. Configure invalidation/freshness for that result separately. A type-level
+authorization behavior outside the cache does not reproduce every entity check.
+
+Use `createPartitionedCacheKeyFactory`. It partitions every dimension that can
+change an authorized response, escapes each segment so `a:b` + `c` cannot collide
+with `a` + `b:c`, and fails closed with `MissingCachePartitionError` when a
+required dimension is absent:
+
+```typescript
+import { createPartitionedCacheKeyFactory } from '@nestjs-pipeline/cache';
+
+@UsePipeline([CacheBehavior, {
+  key: createPartitionedCacheKeyFactory({
+    principal: (ctx) => ctx.items.get('currentUserId') as string | undefined,
+    // Include a role-set hash or capability version, otherwise a principal whose
+    // permissions were revoked keeps reading the old response until it expires.
+    scope: (ctx) => ctx.items.get('capabilityVersion') as string | undefined,
+  }),
+}])
+export class GetUsersHandler {}
+```
+
+For genuinely public responses that are identical for every caller:
+
+```typescript
+createPartitionedCacheKeyFactory({
+  principal: () => 'public',
+  requirePrincipal: false,
+  requireTenant: false,
+  requireScope: false,
+});
+```
+
+The permission scope is required by default: creating a factory without a
+`scope` resolver throws unless `requireScope: false` declares that responses do
+not depend on the caller's permissions, and a resolver that returns nothing
+throws `MissingCachePartitionError` at request time.
+
+The tenant options are the same for the cache, idempotency and rate-limit key factories
+(`TenantPartitionOptions` of `@nestjs-pipeline/core`): `includeTenant` (default `true`)
+puts the tenant in the key, and `requireTenant` (default: `includeTenant`) refuses a
+missing one. The three packages' partition errors extend `MissingPartitionError`.
+
+The request payload is included as a SHA-256 digest, so secrets and search terms
+stay out of Redis key listings. The digest is built with `stableStringify` from `@cqrs-ddd/safe-stringify` (not re-exported by this package), which
+sorts object keys recursively so structurally equal payloads map to the same
+entry. It accepts `null`, booleans, finite numbers, strings, arrays, record-like
+objects, and valid dates (converted to ISO strings). Lossy native JSON cases such
+as `Map`, `Set`, `RegExp`, `Error`, binary values, non-finite numbers,
+`undefined`, bigint, functions, symbols, and cycles are rejected instead of
+risking a collision.
+
+Because a cache hit returns before the handler runs, it also skips whatever
+entity-level authorization and field filtering the handler performs. That is why
+tenant, principal and scope are all required by the helper by default. Opt out
+of each explicitly with `requireTenant: false`, `requirePrincipal: false` or
+`requireScope: false`.
+
+A caught `MissingCachePartitionError` names the missing dimension:
+
+```typescript
+import { MissingCachePartitionError } from '@nestjs-pipeline/cache';
+
+if (error instanceof MissingCachePartitionError) {
+  // error.name === 'MissingCachePartitionError'; map it to 401/403 in your filter
+}
+```
+
+### Tenant partitioning
+
+The tenant segment of the key is `context.tenantId`, not a value on
+`context.items`. The pipeline takes it from the tenant source configured on
+`PipelineModule.forRoot()`; the cache package does not import
+`@nestjs-pipeline/tenant`:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { PipelineModule } from '@nestjs-pipeline/core';
+import { tenantSource } from '@nestjs-pipeline/tenant';
+import { CacheBehavior, CacheModule } from '@nestjs-pipeline/cache';
+
+@Module({
+  imports: [
+    CacheModule.forRoot({ ttl: 30_000 }),
+    PipelineModule.forRoot({
+      sources: { tenantId: tenantSource },
+      behaviors: [CacheBehavior],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+For a single-tenant deployment, leave the tenant out of the key:
+
+```typescript
+createPartitionedCacheKeyFactory({
+  includeTenant: false,
+  principal: (ctx) => ctx.items.get('currentUserId') as string | undefined,
+  scope: (ctx) => ctx.items.get('capabilityVersion') as string | undefined,
+});
+```
+
+The correlation id is never part of the key (see above).
+
+### Sharing a key factory through module defaults
+
+Set the factory once in `defaults` and opt in per handler with
+`inheritModuleKey: true`; `cache()` rejects a call with neither `key` nor
+`inheritModuleKey` at compile time:
+
+```typescript
+CacheModule.forRoot({
+  ttl: 30_000,
+  defaults: {
+    key: createPartitionedCacheKeyFactory({
+      principal: (ctx) => ctx.items.get('currentUserId') as string | undefined,
+      scope: (ctx) => ctx.items.get('capabilityVersion') as string | undefined,
+    }),
+  },
+});
+
+@QueryHandler(ListOrdersQuery)
+@UsePipeline(cache({ inheritModuleKey: true, ttl: 10_000 }))
+export class ListOrdersHandler {}
+```
+
+### Conditional caching
+
+`condition` returns `false` to bypass the cache for one request:
+
+```typescript
+@UsePipeline(cache({
+  inheritModuleKey: true,
+  condition: (ctx) => (ctx.request as { fresh?: boolean }).fresh !== true,
+}))
+export class GetReportHandler {}
+```
+
+### Options resolution
+
+Effective options for a handler are resolved as:
+
+1. Module-wide defaults bound via `CacheModule.forRoot({ ttl, defaults })`.
+2. Per-handler options from `@UsePipeline([CacheBehavior, { ... }])`,
+   shallow-merged on top (handler keys win).
+
+### Context items
+
+The behavior records diagnostics on `context.items`:
+
+| Item Token | Type | Meaning |
+| ---------- | ---- | ------- |
+| `CACHE_HIT_ITEM` | `boolean` | Whether the request was served from cache. |
+| `CACHE_KEY_ITEM` | `string` | The resolved cache key. |
+
+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`.
+
+
+---
+
+## Configuration
+
+`CacheModuleOptions` (passed to `CacheModule.forRoot`):
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `cache` | `Cache` | Pre-built `cache-manager` instance (escape hatch). |
+| `stores` | `Keyv[]` | Pre-built Keyv stores (tiered). |
+| `store` | `CacheStoreConfig \| CacheStoreConfig[]` | Declarative store(s). |
+| `ttl` | `number` | Default TTL (ms) for stores and handlers. |
+| `nonBlocking` | `boolean` | Optimize multi-store reads/writes. |
+| `defaults` | `CacheBehaviorOptions` | Default per-handler options. |
+
+`CacheBehaviorOptions` (per handler and/or module `defaults`):
+
+| Field | Type | Default | Description |
+| ----- | ---- | ------- | ----------- |
+| `kinds` | `Array<'command' \| 'query' \| 'event' \| 'unknown'>` | `['query']` | Request kinds eligible for caching. |
+| `ttl` | `number` | module `ttl` | TTL (ms) for entries written by this handler. |
+| `key` | `(context) => string` | Required | Explicit cache-key factory; use `createPartitionedCacheKeyFactory` for protected responses. |
+| `condition` | `(context) => boolean` | _always_ | Gate whether a request is cached. |
+| `failOpen` | `boolean` | `true` | Log and bypass thrown cache read/write errors; set `false` to propagate them. |
+
+`CacheStoreConfig` (declarative store):
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `type` | `'memory' \| 'redis' \| 'memcache' \| 'sqlite' \| 'postgres'` | Backend to build. |
+| `url` | `string` | Connection string / URI (ignored for `memory`). |
+| `namespace` | `string` | Key prefix for this store. |
+| `ttl` | `number` | Default TTL (ms) for this store. |
+| `options` | `Record<string, unknown>` | Adapter-specific options passed through. |
+
+---
+
+## Behavior Contract & Bootstrap Diagnostics
+
+`CacheBehavior` implements `@nestjs-pipeline/core` behavior contract diagnostics:
+
+### Ordering Constraints
+
+- **Execution order**: Cache lookup must execute **after** CASL authorization (`@nestjs-pipeline/casl:CaslBehavior`) for all active cache request kinds (`kinds: ['query']` by default). This guarantees unauthenticated or unauthorized callers never receive cached responses.
+- **Dynamic evaluation**: The ordering rule evaluates dynamically per handler. For inactive request kinds (e.g. a command handler where cache defaults to queries only), ordering constraints are not enforced.
+
+### Validation Invariants
+
+- **Callable key factory**: Whenever caching is active for a handler's request kind, `key` must be a callable function (`typeof === 'function'`). Strings or non-callable values are rejected fast at bootstrap.
+- **Module defaults**: Application-wide defaults supplied to `CacheModule.forRoot({ defaults: { ... } })` are resolved by `CacheBehavior.resolveEffectiveOptions` and evaluated alongside handler options during bootstrap.
+
+---
+
+## Custom Logger
+
+Diagnostic logger failures do not replace handler results or cache-store errors.
+
+`CacheBehavior` emits `debug` cache hit/miss lines and `warn`/`error` store-failure lines through the logger injected with `LOGGING_BEHAVIOR_LOGGER`, falling back to a standard NestJS `Logger` when that token is not bound. `CacheModule` logs the store-initialization message through a NestJS `Logger` when the cache is built.
+
+---
+
+## API Reference
+
+```ts
+import {
+  CacheModule,
+  CacheBehavior,
+  cache,
+  CACHE_DEFAULT_OPTIONS,
+  PIPELINE_CACHE,
+  CACHE_HIT_ITEM,
+  CACHE_HIT_ITEM_TOKEN,
+  CACHE_KEY_ITEM,
+  CACHE_KEY_ITEM_TOKEN,
+  CacheManagerAdapter,
+  buildCache,
+  buildKeyv,
+  createPartitionedCacheKeyFactory,
+  MissingCachePartitionError,
+  type CachePartitionDimension,
+  type IPipelineCache,
+  type CacheModuleOptions,
+  type CacheModuleAsyncOptions,
+  type CacheBehaviorOptions,
+  type CacheIntentOptions,
+  type CacheStoreConfig,
+  type CacheStoreType,
+  type CacheKeyFactory,
+  type CacheCondition,
+  type PartitionedCacheKeyOptions,
+} from '@nestjs-pipeline/cache';
+```
+
+---
+
+## License
+
+Distributed under a dual license: **AGPLv3** (open source) or a **Commercial
+License**. See [`LICENSE`](https://github.com/aristoteliss/nestjs-pipeline/blob/master/LICENSE) and
+[`COMMERCIAL_LICENSE.txt`](https://github.com/aristoteliss/nestjs-pipeline/blob/master/COMMERCIAL_LICENSE.txt), or contact
+aristotelis@ik.me.

package/dist/adapters/cache-manager.adapter.d.ts

@@ -0,0 +1,21 @@
+import type { Cache } from 'cache-manager';
+/**
+ * Common interface for cache interactions within the pipeline.
+ */
+export interface IPipelineCache {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown, ttl?: number): Promise<unknown>;
+}
+/**
+ * Adapter wrapping a cache-manager Cache instance to reliably expose backend
+ * store errors that cache-manager would otherwise swallow in get().
+ */
+export declare class CacheManagerAdapter {
+    private readonly cache;
+    private readonly operation;
+    constructor(cache: Cache);
+    private captureError;
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown, ttl?: number): Promise<unknown>;
+}
+//# sourceMappingURL=cache-manager.adapter.d.ts.map

package/dist/adapters/cache-manager.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-manager.adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/cache-manager.adapter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE3C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAClE;AAED;;;GAGG;AACH,qBAAa,mBAAmB;IASlB,OAAO,CAAC,QAAQ,CAAC,KAAK;IANlC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAIrB;gBAEwB,KAAK,EAAE,KAAK;IAWzC,OAAO,CAAC,YAAY;IAcd,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASlC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAQvE"}

package/dist/adapters/cache-manager.adapter.js

@@ -0,0 +1,56 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheManagerAdapter = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+/**
+ * Adapter wrapping a cache-manager Cache instance to reliably expose backend
+ * store errors that cache-manager would otherwise swallow in get().
+ */
+class CacheManagerAdapter {
+    cache;
+    // cache-manager emits errors in the originating operation's async context.
+    // A key alone cannot identify concurrent reads, writes, or fallback lookups.
+    operation = new node_async_hooks_1.AsyncLocalStorage();
+    constructor(cache) {
+        this.cache = cache;
+        // A caller-supplied store may swallow backend errors, which then read as a
+        // miss; these listeners surface what it reports.
+        const emitter = cache;
+        emitter.on?.('get', (event) => this.captureError('get', event));
+        emitter.on?.('set', (event) => this.captureError('set', event));
+        emitter.on?.('error', (event) => this.captureError(undefined, event));
+    }
+    captureError(kind, event) {
+        const operation = this.operation.getStore();
+        if (!operation || (kind && operation.kind !== kind))
+            return;
+        if (event &&
+            typeof event === 'object' &&
+            'key' in event &&
+            event.key === operation.key &&
+            'error' in event) {
+            operation.error = event.error;
+        }
+    }
+    async get(key) {
+        return this.operation.run({ key, kind: 'get' }, async () => {
+            const value = await this.cache.get(key);
+            const error = this.operation.getStore()?.error;
+            if (value === undefined && error !== undefined)
+                throw error;
+            return value;
+        });
+    }
+    async set(key, value, ttl) {
+        return this.operation.run({ key, kind: 'set' }, async () => {
+            const result = await this.cache.set(key, value, ttl);
+            const error = this.operation.getStore()?.error;
+            if (error !== undefined)
+                throw error;
+            return result;
+        });
+    }
+}
+exports.CacheManagerAdapter = CacheManagerAdapter;
+//# sourceMappingURL=cache-manager.adapter.js.map

package/dist/adapters/cache-manager.adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-manager.adapter.js","sourceRoot":"","sources":["../../src/adapters/cache-manager.adapter.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AAEtE,uDAAqD;AAWrD;;;GAGG;AACH,MAAa,mBAAmB;IASD;IAR7B,2EAA2E;IAC3E,6EAA6E;IAC5D,SAAS,GAAG,IAAI,oCAAiB,EAI9C,CAAC;IAEL,YAA6B,KAAY;QAAZ,UAAK,GAAL,KAAK,CAAO;QACvC,2EAA2E;QAC3E,iDAAiD;QACjD,MAAM,OAAO,GAAG,KAEf,CAAC;QACF,OAAO,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;QAChE,OAAO,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;QAChE,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC;IACxE,CAAC;IAEO,YAAY,CAAC,IAA+B,EAAE,KAAc;QAClE,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC;QAC5C,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,IAAI,SAAS,CAAC,IAAI,KAAK,IAAI,CAAC;YAAE,OAAO;QAC5D,IACE,KAAK;YACL,OAAO,KAAK,KAAK,QAAQ;YACzB,KAAK,IAAI,KAAK;YACd,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,GAAG;YAC3B,OAAO,IAAI,KAAK,EAChB,CAAC;YACD,SAAS,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAChC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,KAAK,IAAI,EAAE;YACzD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACxC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,KAAK,CAAC;YAC/C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS;gBAAE,MAAM,KAAK,CAAC;YAC5D,OAAO,KAAK,CAAC;QACf,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAc,EAAE,GAAY;QACjD,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,KAAK,IAAI,EAAE;YACzD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;YACrD,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,KAAK,CAAC;YAC/C,IAAI,KAAK,KAAK,SAAS;gBAAE,MAAM,KAAK,CAAC;YACrC,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAnDD,kDAmDC"}