@nestjs-redisx/cache 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NestJS RedisX Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/nestjs-redisx/nestjs-redisx/main/website/public/images/logo.png" alt="NestJS RedisX" />
+</p>
+
+# @nestjs-redisx/cache
+
+[![npm](https://img.shields.io/npm/v/@nestjs-redisx/cache)](https://www.npmjs.com/package/@nestjs-redisx/cache)
+[![npm downloads](https://img.shields.io/npm/dm/@nestjs-redisx/cache)](https://www.npmjs.com/package/@nestjs-redisx/cache)
+[![license](https://img.shields.io/npm/l/@nestjs-redisx/cache)](https://opensource.org/licenses/MIT)
+
+Two-tier caching plugin for NestJS RedisX. L1 in-memory + L2 Redis with anti-stampede protection, stale-while-revalidate (SWR), tag-based invalidation, and declarative `@Cached` decorator.
+
+## Installation
+
+```bash
+npm install @nestjs-redisx/core @nestjs-redisx/cache ioredis
+```
+
+## Quick Example
+
+```typescript
+import { RedisModule } from '@nestjs-redisx/core';
+import { CachePlugin, Cached } from '@nestjs-redisx/cache';
+
+@Module({
+  imports: [
+    RedisModule.forRoot({
+      clients: { host: 'localhost', port: 6379 },
+      plugins: [new CachePlugin({ l1: { maxSize: 1000 }, l2: { defaultTtl: 3600 } })],
+    }),
+  ],
+})
+export class AppModule {}
+
+@Injectable()
+export class UserService {
+  @Cached({ key: 'user:{0}', ttl: 300, tags: ['users'] })
+  async getUser(id: string) {
+    return this.repo.findById(id);
+  }
+}
+```
+
+## Documentation
+
+Full documentation: [nestjs-redisx.dev/en/reference/cache/](https://nestjs-redisx.dev/en/reference/cache/)
+
+## License
+
+MIT

package/dist/cache/api/decorators/cached.decorator.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @Cached decorator for method-level caching.
+ *
+ * Uses immediate proxy-based wrapping (not deferred to module init).
+ * Works on ANY Injectable class methods (services, repositories, etc).
+ */
+import 'reflect-metadata';
+/**
+ * Cache service interface for decorator use.
+ * Minimal subset of ICacheService needed by decorators.
+ */
+interface IDecoratorCacheService {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, options?: {
+        ttl?: number;
+        tags?: string[];
+        strategy?: 'l1-only' | 'l2-only' | 'l1-l2';
+    }): Promise<void>;
+    getOrSet<T>(key: string, loader: () => Promise<T>, options?: {
+        ttl?: number;
+        tags?: string[];
+        strategy?: 'l1-only' | 'l2-only' | 'l1-l2';
+        swr?: {
+            enabled?: boolean;
+            staleTime?: number;
+        };
+    }): Promise<T>;
+    invalidateTags(tags: string[]): Promise<number>;
+    deleteMany(keys: string[]): Promise<number>;
+}
+/**
+ * Context provider interface for decorator use.
+ */
+interface IDecoratorContextProvider {
+    get<T = unknown>(key: string): T | undefined;
+}
+/**
+ * Plugin options subset needed by decorators for context enrichment.
+ */
+interface IDecoratorPluginOptions {
+    contextProvider?: IDecoratorContextProvider;
+    contextKeys?: string[];
+    keys?: {
+        separator?: string;
+    };
+}
+/**
+ * Register cache service getter for lazy injection.
+ * Called by CacheDecoratorInitializerService during initialization.
+ */
+export declare function registerCacheServiceGetter(getter: () => IDecoratorCacheService): void;
+/**
+ * Register plugin options for context enrichment in decorators.
+ * Called by CacheDecoratorInitializerService during initialization.
+ */
+export declare function registerCachePluginOptions(options: IDecoratorPluginOptions): void;
+/**
+ * Get the registered cache service.
+ * Used by other cache decorators (@InvalidateTags, etc.)
+ */
+export declare function getCacheService(): IDecoratorCacheService | null;
+export interface ICachedOptions {
+    /**
+     * Cache key template. Use {0}, {1}, etc. for method arguments.
+     * Example: 'user:{0}' for first argument.
+     *
+     * If omitted, key is auto-generated as `ClassName:methodName:args`.
+     */
+    key?: string;
+    /**
+     * TTL in seconds. Defaults to plugin's defaultTtl.
+     */
+    ttl?: number;
+    /**
+     * Tags for invalidation. Can be static array or function of args.
+     */
+    tags?: string[] | ((...args: unknown[]) => string[]);
+    /**
+     * Cache strategy: where to store the cached value.
+     * - 'l1-only': Only in-memory cache
+     * - 'l2-only': Only Redis cache
+     * - 'l1-l2': Both layers (default)
+     */
+    strategy?: 'l1-only' | 'l2-only' | 'l1-l2';
+    /**
+     * Condition to check BEFORE method execution.
+     * If returns false, skip caching and execute method.
+     */
+    condition?: (...args: unknown[]) => boolean;
+    /**
+     * Condition to check AFTER method execution.
+     * If returns true, don't cache the result.
+     */
+    unless?: (result: unknown, ...args: unknown[]) => boolean;
+    /**
+     * Additional context keys to vary cache by.
+     * Values are resolved from contextProvider at call time.
+     * Adds to (not replaces) global contextKeys.
+     *
+     * Works on any Injectable — values come from contextProvider (CLS, AsyncLocalStorage, etc.),
+     * not from HTTP headers. Ignored if contextProvider is not configured.
+     *
+     * @example
+     * ```typescript
+     * @Cached({
+     *   key: 'products',
+     *   varyBy: ['locale', 'currency']  // resolved from contextProvider
+     * })
+     * ```
+     */
+    varyBy?: string[];
+    /**
+     * Stale-while-revalidate configuration.
+     * If enabled, serves stale data while revalidating in background.
+     */
+    swr?: {
+        enabled?: boolean;
+        staleTime?: number;
+    };
+    /**
+     * Context keys to include in cache key (from contextProvider).
+     * Overrides global contextKeys for this method.
+     */
+    contextKeys?: string[];
+    /**
+     * Disable context enrichment for this method.
+     * Set to true to prevent automatic context keys from being added.
+     *
+     * @default false
+     */
+    skipContext?: boolean;
+}
+/**
+ * Caches method return value using immediate proxy-based wrapping.
+ *
+ * Works on any Injectable class method, not just controllers.
+ * Wrapping happens immediately when decorator is applied.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class UserService {
+ *   @Cached({ key: 'user:{0}', ttl: 3600, tags: ['users'] })
+ *   async getUser(id: string): Promise<User> {
+ *     return this.userRepository.findById(id);
+ *   }
+ * }
+ * ```
+ */
+export declare function Cached(options?: ICachedOptions): MethodDecorator;
+export {};
+//# sourceMappingURL=cached.decorator.d.ts.map

package/dist/cache/api/decorators/cached.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached.decorator.d.ts","sourceRoot":"","sources":["../../../../src/cache/api/decorators/cached.decorator.ts"],"names":[],"mappings":"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"}

package/dist/cache/api/decorators/invalidate-tags.decorator.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @InvalidateTags decorator for automatic tag invalidation.
+ *
+ * Uses immediate proxy-based wrapping (not deferred to interceptor).
+ * Works on ANY Injectable class methods (services, repositories, etc).
+ */
+import 'reflect-metadata';
+export interface IInvalidateTagsOptions {
+    /**
+     * Tags to invalidate. Can be static array or function of method args.
+     */
+    tags: string[] | ((...args: unknown[]) => string[]);
+    /**
+     * When to invalidate: 'before' or 'after' method execution.
+     * Default: 'after'
+     */
+    when?: 'before' | 'after';
+}
+/**
+ * Invalidates cache tags when method is called.
+ *
+ * Works on any Injectable class method, not just controllers.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class UserService {
+ *   @InvalidateTags({
+ *     tags: (id: string) => [`user:${id}`, 'users'],
+ *     when: 'after',
+ *   })
+ *   async updateUser(id: string, data: UpdateUserDto): Promise<User> {
+ *     return this.userRepository.update(id, data);
+ *   }
+ *
+ *   @InvalidateTags({ tags: ['users'] })
+ *   async deleteUser(id: string): Promise<void> {
+ *     await this.userRepository.delete(id);
+ *   }
+ * }
+ * ```
+ */
+export declare function InvalidateTags(options: IInvalidateTagsOptions): MethodDecorator;
+//# sourceMappingURL=invalidate-tags.decorator.d.ts.map

package/dist/cache/api/decorators/invalidate-tags.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidate-tags.decorator.d.ts","sourceRoot":"","sources":["../../../../src/cache/api/decorators/invalidate-tags.decorator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,kBAAkB,CAAC;AAM1B,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC,CAAC;IAEpD;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,sBAAsB,GAAG,eAAe,CA+C/E"}

package/dist/cache/application/ports/cache-service.port.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Main cache service interface (port).
+ */
+import { CacheSetOptions, CacheGetOrSetOptions, CacheStats } from '../../../shared/types';
+/**
+ * Main cache service interface.
+ */
+export interface ICacheService {
+    /**
+     * Gets value from cache (L1 -> L2).
+     *
+     * @param key - Cache key
+     * @returns Cached value or null if not found
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Sets value in cache.
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param options - Cache options
+     */
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    /**
+     * Deletes key from both caches.
+     *
+     * @param key - Cache key
+     * @returns true if deleted, false if not found
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Checks if key exists in cache.
+     *
+     * @param key - Cache key
+     * @returns true if exists, false otherwise
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Gets value or loads and caches it.
+     * Implements stampede protection.
+     *
+     * @param key - Cache key
+     * @param loader - Function to load value if cache miss
+     * @param options - Cache options
+     * @returns Cached or loaded value
+     */
+    getOrSet<T>(key: string, loader: () => Promise<T>, options?: CacheGetOrSetOptions): Promise<T>;
+    /**
+     * Gets multiple values from cache.
+     *
+     * @param keys - Array of cache keys
+     * @returns Array of values (null if not found)
+     */
+    getMany<T>(keys: string[]): Promise<Array<T | null>>;
+    /**
+     * Sets multiple values in cache.
+     *
+     * @param entries - Array of entries with key, value, and optional options
+     */
+    setMany<T>(entries: Array<{
+        key: string;
+        value: T;
+        ttl?: number;
+        tags?: string[];
+    }>): Promise<void>;
+    /**
+     * Deletes multiple keys from cache.
+     *
+     * @param keys - Array of cache keys
+     * @returns Number of keys deleted
+     */
+    deleteMany(keys: string[]): Promise<number>;
+    /**
+     * Invalidates all keys with given tag.
+     *
+     * @param tag - Tag name
+     * @returns Number of keys invalidated
+     */
+    invalidateTag(tag: string): Promise<number>;
+    /**
+     * Invalidates all keys with any of given tags.
+     *
+     * @param tags - Array of tag names
+     * @returns Number of keys invalidated
+     */
+    invalidateTags(tags: string[]): Promise<number>;
+    /**
+     * Gets all keys associated with a tag.
+     *
+     * @param tag - Tag name
+     * @returns Array of cache keys
+     */
+    getKeysByTag(tag: string): Promise<string[]>;
+    /**
+     * Gets TTL for a key in seconds.
+     *
+     * @param key - Cache key
+     * @returns TTL in seconds, -1 if no TTL, -2 if key doesn't exist
+     */
+    ttl(key: string): Promise<number>;
+    /**
+     * Clears all caches (L1 + L2).
+     */
+    clear(): Promise<void>;
+    /**
+     * Gets cache statistics.
+     *
+     * @returns Cache stats
+     */
+    getStats(): Promise<CacheStats>;
+    /**
+     * Invalidates cache keys matching a pattern.
+     * Uses Redis SCAN for safe iteration.
+     *
+     * @param pattern - Redis pattern (supports * and ?)
+     * @returns Number of keys deleted
+     */
+    invalidateByPattern(pattern: string): Promise<number>;
+}
+//# sourceMappingURL=cache-service.port.d.ts.map

package/dist/cache/application/ports/cache-service.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-service.port.d.ts","sourceRoot":"","sources":["../../../../src/cache/application/ports/cache-service.port.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAE1F;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEvC;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExE;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtC;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnC;;;;;;;;OAQG;IACH,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAE/F;;;;;OAKG;IACH,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAErD;;;;OAIG;IACH,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpG;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5C;;;;;OAKG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5C;;;;;OAKG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEhD;;;;;OAKG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE7C;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAElC;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAEhC;;;;;;OAMG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvD"}

package/dist/cache/application/ports/l1-cache-store.port.d.ts

@@ -0,0 +1,56 @@
+/**
+ * L1 (in-memory) cache store interface.
+ */
+import { CacheEntry } from '../../domain/value-objects/cache-entry.vo';
+export interface IL1CacheStore {
+    /**
+     * Gets value from L1 cache.
+     *
+     * @param key - Cache key
+     * @returns CacheEntry or null if not found/expired
+     */
+    get<T>(key: string): Promise<CacheEntry<T> | null>;
+    /**
+     * Sets value in L1 cache.
+     *
+     * @param key - Cache key
+     * @param entry - CacheEntry to store
+     * @param ttl - TTL in milliseconds (optional, uses default if not provided)
+     */
+    set<T>(key: string, entry: CacheEntry<T>, ttl?: number): Promise<void>;
+    /**
+     * Deletes value from L1 cache.
+     *
+     * @param key - Cache key
+     * @returns true if existed, false otherwise
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Checks if key exists in L1 cache.
+     *
+     * @param key - Cache key
+     * @returns true if exists and not expired
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Gets current size of L1 cache.
+     *
+     * @returns Number of items in cache
+     */
+    size(): Promise<number>;
+    /**
+     * Clears all items from L1 cache.
+     */
+    clear(): Promise<void>;
+    /**
+     * Gets L1 cache statistics.
+     *
+     * @returns Cache statistics (hits, misses, size)
+     */
+    getStats(): {
+        hits: number;
+        misses: number;
+        size: number;
+    };
+}
+//# sourceMappingURL=l1-cache-store.port.d.ts.map

package/dist/cache/application/ports/l1-cache-store.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"l1-cache-store.port.d.ts","sourceRoot":"","sources":["../../../../src/cache/application/ports/l1-cache-store.port.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,2CAA2C,CAAC;AAEvE,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnD;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtC;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnC;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAExB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5D"}

package/dist/cache/application/ports/l2-cache-store.port.d.ts

@@ -0,0 +1,98 @@
+/**
+ * L2 (Redis) cache store interface.
+ */
+import { SwrEntry } from '../../../shared/types';
+import { CacheEntry } from '../../domain/value-objects/cache-entry.vo';
+export interface IL2CacheStore {
+    /**
+     * Gets cache entry from L2 cache.
+     *
+     * @param key - Cache key
+     * @returns CacheEntry or null if not found
+     */
+    get<T>(key: string): Promise<CacheEntry<T> | null>;
+    /**
+     * Sets cache entry in L2 cache.
+     *
+     * @param key - Cache key
+     * @param entry - Cache entry to store
+     * @param ttlSeconds - TTL in seconds (optional)
+     */
+    set<T>(key: string, entry: CacheEntry<T>, ttlSeconds?: number): Promise<void>;
+    /**
+     * Deletes value from L2 cache.
+     *
+     * @param key - Cache key
+     * @returns true if deleted, false if not found
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Checks if key exists in L2 cache.
+     *
+     * @param key - Cache key
+     * @returns true if exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Clears all cache entries.
+     * WARNING: This is a destructive operation.
+     */
+    clear(): Promise<void>;
+    /**
+     * Gets multiple cache entries from L2 cache.
+     *
+     * @param keys - Array of cache keys
+     * @returns Map of key -> CacheEntry (null if not found)
+     */
+    getMany<T>(keys: string[]): Promise<Array<CacheEntry<T> | null>>;
+    /**
+     * Sets multiple cache entries in L2 cache.
+     *
+     * @param entries - Array of entries with key, entry, and optional ttl
+     */
+    setMany<T>(entries: Array<{
+        key: string;
+        entry: CacheEntry<T>;
+        ttl?: number;
+    }>): Promise<void>;
+    /**
+     * Gets TTL for a key.
+     *
+     * @param key - Cache key
+     * @returns TTL in seconds, -1 if no TTL, -2 if key doesn't exist
+     */
+    ttl(key: string): Promise<number>;
+    /**
+     * Gets L2 cache statistics.
+     */
+    getStats(): Promise<{
+        hits: number;
+        misses: number;
+    }>;
+    /**
+     * Gets SWR entry from L2 cache with metadata.
+     *
+     * @param key - Cache key
+     * @returns SwrEntry with timestamps or null if not found
+     */
+    getSwr<T>(key: string): Promise<SwrEntry<T> | null>;
+    /**
+     * Sets SWR entry in L2 cache with metadata.
+     *
+     * @param key - Cache key
+     * @param swrEntry - SWR entry with value and timestamps
+     */
+    setSwr<T>(key: string, swrEntry: SwrEntry<T>): Promise<void>;
+    /**
+     * Scans keys matching a pattern using Redis SCAN.
+     *
+     * @param pattern - Redis pattern (supports * and ?)
+     * @param count - Hint for number of elements per SCAN iteration
+     * @returns Scan result with matching keys and cursor
+     */
+    scan(pattern: string, count?: number): Promise<{
+        keys: string[];
+        cursor: string;
+    }>;
+}
+//# sourceMappingURL=l2-cache-store.port.d.ts.map

package/dist/cache/application/ports/l2-cache-store.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"l2-cache-store.port.d.ts","sourceRoot":"","sources":["../../../../src/cache/application/ports/l2-cache-store.port.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,2CAA2C,CAAC;AAEvE,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnD;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9E;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtC;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnC;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;;OAKG;IACH,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAEjE;;;;OAIG;IACH,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/F;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAElC;;OAEG;IACH,QAAQ,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEtD;;;;;OAKG;IACH,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEpD;;;;;OAKG;IACH,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7D;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpF"}

package/dist/cache/application/services/cache-decorator-initializer.service.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Service for initializing @Cached decorator with lazy cache service injection.
+ *
+ * Runs on module initialization and registers a getter function that provides
+ * access to CacheService for the @Cached decorator's proxy logic.
+ */
+import { OnModuleInit } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import { IEventInvalidationService } from '../../../invalidation/application/ports/event-invalidation.port';
+import { ICachePluginOptions } from '../../../shared/types';
+import { ICacheService } from '../ports/cache-service.port';
+export declare class CacheDecoratorInitializerService implements OnModuleInit {
+    private readonly moduleRef;
+    private readonly cacheService;
+    private readonly pluginOptions;
+    private readonly eventInvalidationService?;
+    private readonly logger;
+    constructor(moduleRef: ModuleRef, cacheService: ICacheService, pluginOptions: ICachePluginOptions, eventInvalidationService?: IEventInvalidationService | undefined);
+    /**
+     * Called after all modules are initialized.
+     * Registers cache service getter and plugin options for @Cached decorator.
+     */
+    onModuleInit(): Promise<void>;
+}
+//# sourceMappingURL=cache-decorator-initializer.service.d.ts.map

package/dist/cache/application/services/cache-decorator-initializer.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-decorator-initializer.service.d.ts","sourceRoot":"","sources":["../../../../src/cache/application/services/cache-decorator-initializer.service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAc,YAAY,EAA4B,MAAM,gBAAgB,CAAC;AACpF,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAE,yBAAyB,EAAE,MAAM,iEAAiE,CAAC;AAG5G,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,qBACa,gCAAiC,YAAW,YAAY;IAIjE,OAAO,CAAC,QAAQ,CAAC,SAAS;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY;IACtB,OAAO,CAAC,QAAQ,CAAC,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAC;IAN5F,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqD;gBAGzD,SAAS,EAAE,SAAS,EACG,YAAY,EAAE,aAAa,EACpB,aAAa,EAAE,mBAAmB,EAChB,wBAAwB,CAAC,EAAE,yBAAyB,YAAA;IAGvH;;;OAGG;IAEG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;CAkBpC"}