@nestjs-redisx/cache 1.0.0

package/dist/cache.service.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Main cache service.
+ * Simplified API wrapper over the internal cache implementation.
+ */
+import { ICacheService as IInternalCacheService } from './cache/application/ports/cache-service.port';
+import { CacheSetOptions, CacheGetOrSetOptions, CacheStats } from './shared/types';
+export declare class CacheService {
+    private readonly internalCache;
+    constructor(internalCache: IInternalCacheService);
+    /**
+     * Gets value from cache.
+     *
+     * @param key - Cache key
+     * @returns Cached value or null if not found
+     *
+     * @example
+     * ```typescript
+     * const user = await cacheService.get<User>('user:123');
+     * ```
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Sets value in cache with optional TTL and tags.
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param options - Cache options (ttl, tags, strategy)
+     *
+     * @example
+     * ```typescript
+     * await cacheService.set('user:123', user, {
+     *   ttl: 3600,
+     *   tags: ['users', 'user:123']
+     * });
+     * ```
+     */
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    /**
+     * Deletes key from cache.
+     *
+     * @param key - Cache key
+     * @returns True if key was deleted, false if not found
+     *
+     * @example
+     * ```typescript
+     * const deleted = await cacheService.del('user:123');
+     * ```
+     */
+    del(key: string): Promise<boolean>;
+    /**
+     * Gets multiple values from cache.
+     *
+     * @param keys - Array of cache keys
+     * @returns Array of values (null for missing keys)
+     *
+     * @example
+     * ```typescript
+     * const users = await cacheService.getMany<User>(['user:1', 'user:2', 'user:3']);
+     * ```
+     */
+    getMany<T>(keys: string[]): Promise<Array<T | null>>;
+    /**
+     * Sets multiple values in cache.
+     *
+     * @param entries - Array of key-value-ttl tuples
+     *
+     * @example
+     * ```typescript
+     * await cacheService.setMany([
+     *   { key: 'user:1', value: user1, ttl: 3600 },
+     *   { key: 'user:2', value: user2, ttl: 3600 }
+     * ]);
+     * ```
+     */
+    setMany<T>(entries: Array<{
+        key: string;
+        value: T;
+        ttl?: number;
+    }>): Promise<void>;
+    /**
+     * Gets value from cache or loads it using the provided loader function.
+     * Implements cache-aside pattern with anti-stampede protection.
+     *
+     * @param key - Cache key
+     * @param loader - Function to load value if not cached
+     * @param options - Cache options
+     * @returns Cached or loaded value
+     *
+     * @example
+     * ```typescript
+     * const user = await cacheService.getOrSet(
+     *   'user:123',
+     *   async () => {
+     *     return await userRepository.findById('123');
+     *   },
+     *   { ttl: 3600, tags: ['users'] }
+     * );
+     * ```
+     */
+    getOrSet<T>(key: string, loader: () => Promise<T>, options?: CacheGetOrSetOptions): Promise<T>;
+    /**
+     * Wraps a function with caching logic.
+     * Helper for creating cached functions.
+     *
+     * @param fn - Function to wrap
+     * @param options - Cache options or key builder function
+     * @returns Wrapped function with caching
+     *
+     * @example
+     * ```typescript
+     * const getCachedUser = cacheService.wrap(
+     *   async (id: string) => userRepository.findById(id),
+     *   {
+     *     key: (id: string) => `user:${id}`,
+     *     ttl: 3600,
+     *     tags: (id: string) => [`user:${id}`, 'users']
+     *   }
+     * );
+     *
+     * const user = await getCachedUser('123');
+     * ```
+     */
+    wrap<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>, options: {
+        key: (...args: TArgs) => string;
+        ttl?: number;
+        tags?: string[] | ((...args: TArgs) => string[]);
+    }): (...args: TArgs) => Promise<TReturn>;
+    /**
+     * Deletes multiple keys from cache.
+     *
+     * @param keys - Array of cache keys
+     * @returns Number of keys deleted
+     *
+     * @example
+     * ```typescript
+     * const count = await cacheService.deleteMany(['user:1', 'user:2', 'user:3']);
+     * console.log(`Deleted ${count} keys`);
+     * ```
+     */
+    deleteMany(keys: string[]): Promise<number>;
+    /**
+     * Gets all cache keys associated with a tag.
+     *
+     * @param tag - Tag name
+     * @returns Array of cache keys
+     *
+     * @example
+     * ```typescript
+     * const keys = await cacheService.getKeysByTag('users');
+     * console.log(`Found ${keys.length} cached user keys`);
+     * ```
+     */
+    getKeysByTag(tag: string): Promise<string[]>;
+    /**
+     * Invalidates cache by tag.
+     *
+     * @param tag - Tag to invalidate
+     * @returns Number of keys invalidated
+     *
+     * @example
+     * ```typescript
+     * // Invalidate all user caches
+     * const count = await cacheService.invalidate('users');
+     * console.log(`Invalidated ${count} keys`);
+     * ```
+     */
+    invalidate(tag: string): Promise<number>;
+    /**
+     * Invalidates multiple tags.
+     *
+     * @param tags - Array of tags to invalidate
+     * @returns Total number of keys invalidated
+     *
+     * @example
+     * ```typescript
+     * const count = await cacheService.invalidate(['users', 'products']);
+     * ```
+     */
+    invalidateTags(tags: string[]): Promise<number>;
+    /**
+     * Invalidates cache keys matching a pattern.
+     * Uses Redis SCAN for safe iteration.
+     *
+     * @param pattern - Redis pattern (supports * and ?)
+     * @returns Number of keys deleted
+     *
+     * @example
+     * ```typescript
+     * // Delete all user-related caches
+     * await cacheService.invalidateByPattern('user:*');
+     *
+     * // Delete specific locale caches
+     * await cacheService.invalidateByPattern('*:en_US');
+     * ```
+     */
+    invalidateByPattern(pattern: string): Promise<number>;
+    /**
+     * Checks if key exists in cache.
+     *
+     * @param key - Cache key
+     * @returns True if key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Gets TTL for a cached key.
+     *
+     * @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 cache entries.
+     * Use with caution in production.
+     *
+     * @example
+     * ```typescript
+     * await cacheService.clear();
+     * ```
+     */
+    clear(): Promise<void>;
+    /**
+     * Gets cache statistics.
+     *
+     * @returns Cache stats (hits, misses, size)
+     *
+     * @example
+     * ```typescript
+     * const stats = await cacheService.getStats();
+     * console.log(`L1 Hit Rate: ${stats.l1.hits / (stats.l1.hits + stats.l1.misses) * 100}%`);
+     * ```
+     */
+    getStats(): Promise<CacheStats>;
+}
+//# sourceMappingURL=cache.service.d.ts.map

package/dist/cache.service.d.ts.map

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

package/dist/decorators/cache-evict.decorator.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @CacheEvict decorator for cache invalidation.
+ *
+ * Evicts (removes) cache entries after method execution.
+ * Supports multiple keys, tags, and patterns.
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @CacheEvict({
+ *     keys: ['user:{id}'],
+ *     tags: ['users']
+ *   })
+ *   async updateUser(id: string, data: UpdateUserDto) {
+ *     return this.repository.update(id, data);
+ *   }
+ *
+ *   @CacheEvict({
+ *     keys: ['user:{userId}:posts:*'],
+ *     beforeInvocation: false
+ *   })
+ *   async deleteUserPosts(userId: string) {
+ *     return this.repository.deletePosts(userId);
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Options for @CacheEvict decorator.
+ */
+export interface ICacheEvictOptions {
+    /**
+     * Cache keys or key templates to evict.
+     * Supports parameter interpolation and wildcards.
+     *
+     * @example ['user:{id}']
+     * @example ['user:{userId}:posts:*']
+     */
+    keys?: string[];
+    /**
+     * Tags to invalidate.
+     * All keys with these tags will be evicted.
+     */
+    tags?: string[];
+    /**
+     * Whether to evict all cache entries.
+     * Use with caution - this clears the entire cache.
+     *
+     * @default false
+     */
+    allEntries?: boolean;
+    /**
+     * Whether to evict cache before method invocation.
+     * - true: evict before execution
+     * - false: evict after execution (default)
+     *
+     * @default false
+     */
+    beforeInvocation?: boolean;
+    /**
+     * Condition to determine if cache should be evicted.
+     * Return false to skip eviction for specific cases.
+     */
+    condition?: (...args: unknown[]) => boolean;
+    /**
+     * Custom key generator function.
+     * If provided, overrides template-based key generation.
+     */
+    keyGenerator?: (...args: unknown[]) => string[];
+    /**
+     * Namespace prefix for the keys.
+     * @default ''
+     */
+    namespace?: string;
+}
+/**
+ * Metadata key for @CacheEvict decorator.
+ */
+export declare const CACHE_EVICT_METADATA_KEY = "cache:evict";
+/**
+ * @CacheEvict decorator.
+ *
+ * Automatically evicts cache entries after (or before) method execution.
+ * Supports multiple keys, tags, and pattern matching.
+ *
+ * @param options - Eviction options
+ *
+ * @example
+ * ```typescript
+ * @CacheEvict({ keys: ['user:{id}'], tags: ['users'] })
+ * async updateUser(id: string, data: UpdateUserDto) {
+ *   return await this.repository.update(id, data);
+ * }
+ * ```
+ */
+export declare function CacheEvict(options?: ICacheEvictOptions): MethodDecorator;
+//# sourceMappingURL=cache-evict.decorator.d.ts.map

package/dist/decorators/cache-evict.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-evict.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/cache-evict.decorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAE5C;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;IAEhD;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB,gBAAgB,CAAC;AAEtD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,kBAAuB,GAAG,eAAe,CAE5E"}

package/dist/decorators/cache-put.decorator.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @CachePut decorator for cache updates.
+ *
+ * Always executes the method and updates the cache with the result.
+ * Unlike @Cacheable, it doesn't check the cache before execution.
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @CachePut({
+ *     key: 'user:{id}',
+ *     tags: ['users']
+ *   })
+ *   async updateUser(id: string, data: UpdateUserDto) {
+ *     const updated = await this.repository.update(id, data);
+ *     return updated; // This result will be cached
+ *   }
+ *
+ *   @CachePut({
+ *     key: 'user:{user.id}',
+ *     ttl: 1800
+ *   })
+ *   async createUser(user: CreateUserDto) {
+ *     const created = await this.repository.create(user);
+ *     return created; // This result will be cached
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Options for @CachePut decorator.
+ */
+export interface ICachePutOptions {
+    /**
+     * Cache key template. Supports parameter interpolation.
+     * Use {paramName} to interpolate method parameters.
+     * Supports nested properties: {user.id}
+     *
+     * @example 'user:{id}'
+     * @example 'user:{user.id}'
+     */
+    key: string;
+    /**
+     * TTL in seconds.
+     * @default 3600
+     */
+    ttl?: number;
+    /**
+     * Tags for invalidation.
+     * Can be static array or function that returns array.
+     */
+    tags?: string[] | ((...args: unknown[]) => string[]);
+    /**
+     * Condition to determine if result should be cached.
+     * Return false to skip caching for specific cases.
+     */
+    condition?: (...args: unknown[]) => boolean;
+    /**
+     * Custom key generator function.
+     * If provided, overrides template-based key generation.
+     */
+    keyGenerator?: (...args: unknown[]) => string;
+    /**
+     * Namespace prefix for the key.
+     * @default ''
+     */
+    namespace?: string;
+    /**
+     * Whether to cache null/undefined results.
+     * @default false
+     */
+    cacheNullValues?: boolean;
+}
+/**
+ * Metadata key for @CachePut decorator.
+ */
+export declare const CACHE_PUT_METADATA_KEY = "cache:put";
+/**
+ * @CachePut decorator.
+ *
+ * Always executes the method and caches the result.
+ * Useful for update operations where you want to refresh the cache.
+ *
+ * @param options - Cache put options
+ *
+ * @example
+ * ```typescript
+ * @CachePut({ key: 'user:{id}', ttl: 3600 })
+ * async updateUser(id: string, data: UpdateUserDto) {
+ *   return await this.repository.update(id, data);
+ * }
+ * ```
+ */
+export declare function CachePut(options: ICachePutOptions): MethodDecorator;
+//# sourceMappingURL=cache-put.decorator.d.ts.map

package/dist/decorators/cache-put.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-put.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/cache-put.decorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC,CAAC;IAErD;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAE5C;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,CAAC;IAE9C;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,eAAO,MAAM,sBAAsB,cAAc,CAAC;AAElD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAEnE"}

package/dist/decorators/cache.interceptor.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Cache interceptor for handling @Cacheable, @CachePut, and @CacheEvict decorators.
+ */
+import { NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Observable } from 'rxjs';
+import { CacheService } from '../cache.service';
+/**
+ * Interceptor for cache decorators.
+ *
+ * Handles:
+ * - @Cacheable: Returns cached value or executes and caches result
+ * - @CachePut: Always executes and caches result
+ * - @CacheEvict: Evicts cache entries before or after execution
+ *
+ * @example
+ * ```typescript
+ * @Controller('users')
+ * @UseInterceptors(CacheInterceptor)
+ * export class UserController {
+ *   @Get(':id')
+ *   @Cacheable({ key: 'user:{id}', ttl: 3600 })
+ *   getUser(@Param('id') id: string) {
+ *     return this.userService.findOne(id);
+ *   }
+ *
+ *   @Put(':id')
+ *   @CachePut({ key: 'user:{id}' })
+ *   updateUser(@Param('id') id: string, @Body() data: UpdateUserDto) {
+ *     return this.userService.update(id, data);
+ *   }
+ *
+ *   @Delete(':id')
+ *   @CacheEvict({ keys: ['user:{id}'] })
+ *   deleteUser(@Param('id') id: string) {
+ *     return this.userService.delete(id);
+ *   }
+ * }
+ * ```
+ */
+export declare class CacheInterceptor implements NestInterceptor {
+    private readonly cacheService;
+    private readonly reflector;
+    private readonly logger;
+    constructor(cacheService: CacheService, reflector: Reflector);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+    /**
+     * Handles @Cacheable decorator.
+     * Returns cached value or executes method and caches result.
+     */
+    private handleCacheable;
+    /**
+     * Handles @CachePut decorator.
+     * Always executes method and caches the result.
+     */
+    private handleCachePut;
+    /**
+     * Handles @CacheEvict decorator.
+     * Evicts cache entries before or after method execution.
+     */
+    private handleCacheEvict;
+}
+//# sourceMappingURL=cache.interceptor.d.ts.map

package/dist/decorators/cache.interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.interceptor.d.ts","sourceRoot":"","sources":["../../src/decorators/cache.interceptor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAc,eAAe,EAAE,gBAAgB,EAAE,WAAW,EAAU,MAAM,gBAAgB,CAAC;AACpG,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,UAAU,EAAY,MAAM,MAAM,CAAC;AAG5C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAMhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBACa,gBAAiB,YAAW,eAAe;IAIpD,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;gBAGzC,YAAY,EAAE,YAAY,EAC1B,SAAS,EAAE,SAAS;IAGvC,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC;IAiC5E;;;OAGG;IACH,OAAO,CAAC,eAAe;IAqDvB;;;OAGG;IACH,OAAO,CAAC,cAAc;IA+CtB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;CA8DzB"}

package/dist/decorators/cacheable.decorator.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @Cacheable decorator for automatic method result caching.
+ *
+ * Caches method results and returns cached value on subsequent calls.
+ * Supports key templates with parameter interpolation.
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @Cacheable({
+ *     key: 'user:{id}',
+ *     ttl: 3600,
+ *     tags: ['users']
+ *   })
+ *   async getUser(id: string) {
+ *     return this.repository.findById(id);
+ *   }
+ *
+ *   @Cacheable({
+ *     key: 'user:{userId}:posts:{postId}',
+ *     ttl: 1800
+ *   })
+ *   async getUserPost(userId: string, postId: string) {
+ *     return this.repository.findPost(userId, postId);
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Options for @Cacheable decorator.
+ */
+export interface ICacheableOptions {
+    /**
+     * Cache key template. Supports parameter interpolation.
+     * Use {paramName} to interpolate method parameters.
+     *
+     * @example 'user:{id}'
+     * @example 'post:{userId}:{postId}'
+     */
+    key: string;
+    /**
+     * TTL in seconds.
+     * @default 3600
+     */
+    ttl?: number;
+    /**
+     * Tags for invalidation.
+     * Can be static array or function that returns array.
+     */
+    tags?: string[] | ((...args: unknown[]) => string[]);
+    /**
+     * Condition to determine if result should be cached.
+     * Return false to skip caching for specific cases.
+     */
+    condition?: (...args: unknown[]) => boolean;
+    /**
+     * Custom key generator function.
+     * If provided, overrides template-based key generation.
+     */
+    keyGenerator?: (...args: unknown[]) => string;
+    /**
+     * Namespace prefix for the key.
+     * @default ''
+     */
+    namespace?: string;
+}
+/**
+ * Metadata key for @Cacheable decorator.
+ */
+export declare const CACHEABLE_METADATA_KEY = "cache:cacheable";
+/**
+ * @Cacheable decorator.
+ *
+ * Automatically caches method results using the configured key template.
+ * Supports parameter interpolation in key templates.
+ *
+ * @param options - Caching options
+ *
+ * @example
+ * ```typescript
+ * @Cacheable({ key: 'user:{id}', ttl: 3600 })
+ * async getUser(id: string) {
+ *   return await this.repository.findById(id);
+ * }
+ * ```
+ */
+export declare function Cacheable(options: ICacheableOptions): MethodDecorator;
+//# sourceMappingURL=cacheable.decorator.d.ts.map

package/dist/decorators/cacheable.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheable.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/cacheable.decorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC,CAAC;IAErD;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAE5C;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,CAAC;IAE9C;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,eAAO,MAAM,sBAAsB,oBAAoB,CAAC;AAExD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,iBAAiB,GAAG,eAAe,CAErE"}

package/dist/decorators/key-generator.util.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Utility functions for cache key generation from templates.
+ */
+/**
+ * Extracts parameter names from method signature.
+ *
+ * @param method - Method to extract parameters from
+ * @returns Array of parameter names
+ */
+export declare function getParameterNames(method: Function): string[];
+/**
+ * Gets nested property value from object.
+ *
+ * @param obj - Object to get value from
+ * @param path - Property path (e.g., 'user.id')
+ * @returns Property value or undefined
+ *
+ * @example
+ * getNestedValue({ user: { id: '123' } }, 'user.id') // '123'
+ */
+export declare function getNestedValue(obj: unknown, path: string): unknown;
+/**
+ * Generates cache key from template and method arguments.
+ *
+ * Replaces {paramName} placeholders with actual parameter values.
+ * Supports nested properties: {user.id}
+ *
+ * @param template - Key template (e.g., 'user:{id}')
+ * @param method - Method being decorated
+ * @param args - Method arguments
+ * @param namespace - Optional namespace prefix
+ * @returns Generated cache key
+ *
+ * @throws CacheKeyError if parameter is not found or template is invalid
+ *
+ * @example
+ * ```typescript
+ * generateKey('user:{id}', getUserMethod, ['123']) // 'user:123'
+ * generateKey('user:{user.id}', updateMethod, [{ id: '456' }]) // 'user:456'
+ * ```
+ */
+export declare function generateKey(template: string, method: Function, args: unknown[], namespace?: string): string;
+/**
+ * Generates multiple cache keys from templates and method arguments.
+ *
+ * @param templates - Array of key templates
+ * @param method - Method being decorated
+ * @param args - Method arguments
+ * @param namespace - Optional namespace prefix
+ * @returns Array of generated cache keys
+ */
+export declare function generateKeys(templates: string[], method: Function, args: unknown[], namespace?: string): string[];
+/**
+ * Evaluates tags - either static array or dynamic function.
+ *
+ * @param tags - Tags definition (array or function)
+ * @param args - Method arguments
+ * @returns Array of tag names
+ */
+export declare function evaluateTags(tags: string[] | ((...args: unknown[]) => string[]) | undefined, args: unknown[]): string[];
+/**
+ * Evaluates condition - determines if caching should proceed.
+ *
+ * @param condition - Condition function
+ * @param args - Method arguments
+ * @returns true if caching should proceed
+ */
+export declare function evaluateCondition(condition: ((...args: unknown[]) => boolean) | undefined, args: unknown[]): boolean;
+//# sourceMappingURL=key-generator.util.d.ts.map

package/dist/decorators/key-generator.util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-generator.util.d.ts","sourceRoot":"","sources":["../../src/decorators/key-generator.util.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;;GAKG;AAEH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,EAAE,CAa5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAgBlE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAEhB,MAAM,EAAE,QAAQ,EAChB,IAAI,EAAE,OAAO,EAAE,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAiFR;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EAAE,EAEnB,MAAM,EAAE,QAAQ,EAChB,IAAI,EAAE,OAAO,EAAE,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,EAAE,CAEV;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,EAAE,CAUvH;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAMpH"}