@nestjs-redisx/cache 1.0.0

package/dist/cache/application/services/cache.service.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Main cache service implementation.
+ * Orchestrates L1/L2 caching with stampede protection, SWR, and tag invalidation.
+ */
+import { IRedisDriver } from '@nestjs-redisx/core';
+import { CacheSetOptions, CacheGetOrSetOptions, CacheStats, ICachePluginOptions } from '../../../shared/types';
+import { IStampedeProtection } from '../../../stampede/application/ports/stampede-protection.port';
+import { ISwrManager } from '../../../swr/application/ports/swr-manager.port';
+import { ITagIndex } from '../../../tags/application/ports/tag-index.port';
+import { ICacheService } from '../ports/cache-service.port';
+import { IL1CacheStore } from '../ports/l1-cache-store.port';
+import { IL2CacheStore } from '../ports/l2-cache-store.port';
+interface IMetricsService {
+    incrementCounter(name: string, labels?: Record<string, string>, value?: number): void;
+    setGauge(name: string, value: number, labels?: Record<string, string>): void;
+}
+interface ISpan {
+    setAttribute(key: string, value: unknown): this;
+    addEvent(name: string, attributes?: Record<string, unknown>): this;
+    setStatus(status: 'OK' | 'ERROR'): this;
+    recordException(error: Error): this;
+    end(): void;
+}
+interface ITracingService {
+    startSpan(name: string, options?: {
+        kind?: string;
+        attributes?: Record<string, unknown>;
+    }): ISpan;
+}
+export declare class CacheService implements ICacheService {
+    private readonly driver;
+    private readonly l1Store;
+    private readonly l2Store;
+    private readonly stampede;
+    private readonly tagIndex;
+    private readonly swrManager;
+    private readonly options;
+    private readonly metrics?;
+    private readonly tracing?;
+    private readonly logger;
+    private readonly l1Enabled;
+    private readonly l2Enabled;
+    private readonly stampedeEnabled;
+    private readonly swrEnabled;
+    private readonly tagsEnabled;
+    private readonly keyPrefix;
+    constructor(driver: IRedisDriver, l1Store: IL1CacheStore, l2Store: IL2CacheStore, stampede: IStampedeProtection, tagIndex: ITagIndex, swrManager: ISwrManager, options: ICachePluginOptions, metrics?: IMetricsService | undefined, tracing?: ITracingService | undefined);
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    getOrSet<T>(key: string, loader: () => Promise<T>, options?: CacheGetOrSetOptions): Promise<T>;
+    /**
+     * Loads value with stampede protection if enabled.
+     *
+     * @param key - Normalized cache key
+     * @param loader - Function to load value
+     * @param options - Cache options
+     * @returns Loaded value
+     * @private
+     */
+    private loadWithStampede;
+    delete(key: string): Promise<boolean>;
+    deleteMany(keys: string[]): Promise<number>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    invalidateTag(tag: string): Promise<number>;
+    invalidateTags(tags: string[]): Promise<number>;
+    getKeysByTag(tag: string): Promise<string[]>;
+    getMany<T>(keys: string[]): Promise<Array<T | null>>;
+    setMany<T>(entries: Array<{
+        key: string;
+        value: T;
+        ttl?: number;
+        tags?: string[];
+    }>): Promise<void>;
+    ttl(key: string): Promise<number>;
+    getStats(): Promise<CacheStats>;
+    invalidateByPattern(pattern: string): Promise<number>;
+    /**
+     * Validates and normalizes cache key using CacheKey value object.
+     *
+     * @param rawKey - Raw key string
+     * @returns Normalized key string (without prefix - prefix added by L2 store)
+     * @throws CacheKeyError if validation fails
+     *
+     * @private
+     */
+    private validateAndNormalizeKey;
+    /**
+     * Enriches a normalized key with context values.
+     * Appends global context keys and per-call varyBy values as key suffix.
+     * Uses a marker (_ctx_) to prevent double-enrichment in internal call chains.
+     *
+     * @param normalizedKey - Already validated and normalized cache key
+     * @param varyBy - Optional per-call context overrides
+     * @returns Enriched key with context suffix, or original key if no context
+     * @private
+     */
+    private enrichKeyWithContext;
+    /**
+     * Sanitizes a value for use in cache key (removes non-allowed characters).
+     * @private
+     */
+    private sanitizeForKey;
+}
+export {};
+//# sourceMappingURL=cache.service.d.ts.map

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

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

package/dist/cache/application/services/warmup.service.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Cache warmup service.
+ * Loads specified keys into cache on application startup.
+ */
+import { OnModuleInit } from '@nestjs/common';
+import { ICachePluginOptions } from '../../../shared/types';
+import { ICacheService } from '../ports/cache-service.port';
+export declare class WarmupService implements OnModuleInit {
+    private readonly cacheService;
+    private readonly options;
+    private readonly logger;
+    private readonly enabled;
+    private readonly keys;
+    private readonly concurrency;
+    constructor(cacheService: ICacheService, options: ICachePluginOptions);
+    onModuleInit(): Promise<void>;
+    /**
+     * Warms up a single cache key.
+     *
+     * @param warmupKey - Warmup key configuration
+     * @private
+     */
+    private warmupKey;
+}
+//# sourceMappingURL=warmup.service.d.ts.map

package/dist/cache/application/services/warmup.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warmup.service.d.ts","sourceRoot":"","sources":["../../../../src/cache/application/services/warmup.service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAA8B,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG1E,OAAO,EAAE,mBAAmB,EAAc,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,qBACa,aAAc,YAAW,YAAY;IAOvB,OAAO,CAAC,QAAQ,CAAC,YAAY;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAPxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAGK,YAAY,EAAE,aAAa,EACpB,OAAO,EAAE,mBAAmB;IAOvE,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BnC;;;;;OAKG;YACW,SAAS;CAexB"}

package/dist/cache/domain/services/serializer.service.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Serializer service for cache values.
+ */
+export declare class Serializer {
+    /**
+     * Serializes value to string.
+     *
+     * @param value - Value to serialize
+     * @returns Serialized string
+     * @throws SerializationError if serialization fails
+     */
+    serialize<T>(value: T): string;
+    /**
+     * Deserializes string to value.
+     *
+     * @param serialized - Serialized string
+     * @returns Deserialized value
+     * @throws SerializationError if deserialization fails
+     */
+    deserialize<T>(serialized: string): T;
+    /**
+     * Safely tries to deserialize, returns null on error.
+     *
+     * @param serialized - Serialized string
+     * @returns Deserialized value or null
+     */
+    tryDeserialize<T>(serialized: string): T | null;
+}
+//# sourceMappingURL=serializer.service.d.ts.map

package/dist/cache/domain/services/serializer.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.service.d.ts","sourceRoot":"","sources":["../../../../src/cache/domain/services/serializer.service.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,qBACa,UAAU;IACrB;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM;IAQ9B;;;;;;OAMG;IACH,WAAW,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,CAAC;IAQrC;;;;;OAKG;IACH,cAAc,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;CAOhD"}

package/dist/cache/domain/value-objects/cache-entry.vo.d.ts

@@ -0,0 +1,69 @@
+/**
+ * CacheEntry value object.
+ * Wraps cached value with metadata.
+ */
+export declare class CacheEntry<T> {
+    readonly value: T;
+    readonly cachedAt: number;
+    readonly ttl: number;
+    readonly tags?: string[] | undefined;
+    private constructor();
+    /**
+     * Creates a cache entry.
+     *
+     * @param value - Value to cache
+     * @param ttl - TTL in seconds
+     * @param tags - Optional tags
+     * @returns CacheEntry instance
+     */
+    static create<T>(value: T, ttl: number, tags?: string[]): CacheEntry<T>;
+    /**
+     * Checks if entry is expired.
+     *
+     * @returns true if expired, false otherwise
+     */
+    isExpired(): boolean;
+    /**
+     * Gets time until expiration in milliseconds.
+     *
+     * @returns Milliseconds until expiration (0 if expired)
+     */
+    getTimeToLive(): number;
+    /**
+     * Gets age of entry in milliseconds.
+     *
+     * @returns Age in milliseconds
+     */
+    getAge(): number;
+    /**
+     * Checks if entry has a specific tag.
+     *
+     * @param tag - Tag to check
+     * @returns true if entry has the tag
+     */
+    hasTag(tag: string): boolean;
+    /**
+     * Serializes entry to JSON.
+     *
+     * @returns JSON representation
+     */
+    toJSON(): {
+        value: T;
+        cachedAt: number;
+        ttl: number;
+        tags?: string[];
+    };
+    /**
+     * Deserializes entry from JSON.
+     *
+     * @param json - JSON representation
+     * @returns CacheEntry instance
+     */
+    static fromJSON<T>(json: {
+        value: T;
+        cachedAt: number;
+        ttl: number;
+        tags?: string[];
+    }): CacheEntry<T>;
+}
+//# sourceMappingURL=cache-entry.vo.d.ts.map

package/dist/cache/domain/value-objects/cache-entry.vo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-entry.vo.d.ts","sourceRoot":"","sources":["../../../../src/cache/domain/value-objects/cache-entry.vo.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qBAAa,UAAU,CAAC,CAAC;aAEL,KAAK,EAAE,CAAC;aACR,QAAQ,EAAE,MAAM;aAChB,GAAG,EAAE,MAAM;aACX,IAAI,CAAC,EAAE,MAAM,EAAE;IAJjC,OAAO;IAOP;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC;IAIvE;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAKpB;;;;OAIG;IACH,aAAa,IAAI,MAAM;IAMvB;;;;OAIG;IACH,MAAM,IAAI,MAAM;IAIhB;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B;;;;OAIG;IACH,MAAM,IAAI;QACR,KAAK,EAAE,CAAC,CAAC;QACT,QAAQ,EAAE,MAAM,CAAC;QACjB,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;KACjB;IASD;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE;QAAE,KAAK,EAAE,CAAC,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,UAAU,CAAC,CAAC,CAAC;CAGtG"}

package/dist/cache/domain/value-objects/cache-key.vo.d.ts

@@ -0,0 +1,45 @@
+/**
+ * CacheKey value object.
+ * Validates and builds cache keys with prefix, version, and validation.
+ */
+export interface ICacheKeyOptions {
+    maxLength?: number;
+    prefix?: string;
+    version?: string;
+    separator?: string;
+}
+export declare class CacheKey {
+    private readonly rawKey;
+    private readonly options;
+    private constructor();
+    /**
+     * Creates a validated cache key.
+     *
+     * @param key - Raw key
+     * @param options - Key options
+     * @returns CacheKey instance
+     * @throws CacheKeyError if validation fails
+     */
+    static create(key: string, options?: ICacheKeyOptions): CacheKey;
+    /**
+     * Returns the full cache key with prefix and version.
+     */
+    toString(): string;
+    /**
+     * Returns the raw key without prefix/version.
+     */
+    getRaw(): string;
+    /**
+     * Returns the prefix.
+     */
+    getPrefix(): string;
+    /**
+     * Returns the version.
+     */
+    getVersion(): string;
+    /**
+     * Checks equality with another CacheKey.
+     */
+    equals(other: CacheKey): boolean;
+}
+//# sourceMappingURL=cache-key.vo.d.ts.map

package/dist/cache/domain/value-objects/cache-key.vo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-key.vo.d.ts","sourceRoot":"","sources":["../../../../src/cache/domain/value-objects/cache-key.vo.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AASD,qBAAa,QAAQ;IAEjB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAF1B,OAAO;IAKP;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,QAAQ;IAmCpE;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,MAAM,IAAI,MAAM;IAIhB;;OAEG;IACH,SAAS,IAAI,MAAM;IAInB;;OAEG;IACH,UAAU,IAAI,MAAM;IAIpB;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO;CAGjC"}

package/dist/cache/domain/value-objects/tag.vo.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tag value object.
+ * Validates and normalizes cache tags for invalidation.
+ */
+export declare class Tag {
+    private readonly value;
+    private constructor();
+    /**
+     * Creates a validated tag.
+     *
+     * @param value - Tag value
+     * @param maxLength - Maximum tag length (default: 128)
+     * @returns Tag instance
+     * @throws CacheError if validation fails
+     *
+     * @example
+     * ```typescript
+     * const tag = Tag.create('users');
+     * const productTag = Tag.create('product:123');
+     * ```
+     */
+    static create(value: string, maxLength?: number): Tag;
+    /**
+     * Returns the tag value.
+     */
+    toString(): string;
+    /**
+     * Returns the raw tag value.
+     */
+    getRaw(): string;
+    /**
+     * Checks equality with another tag.
+     */
+    equals(other: Tag): boolean;
+}
+//# sourceMappingURL=tag.vo.d.ts.map

package/dist/cache/domain/value-objects/tag.vo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag.vo.d.ts","sourceRoot":"","sources":["../../../../src/cache/domain/value-objects/tag.vo.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,qBAAa,GAAG;IACM,OAAO,CAAC,QAAQ,CAAC,KAAK;IAA1C,OAAO;IAEP;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,MAA2B,GAAG,GAAG;IAgCzE;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,MAAM,IAAI,MAAM;IAIhB;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO;CAG5B"}

package/dist/cache/domain/value-objects/tags.vo.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Tags collection value object.
+ * Validates and manages a collection of tags with deduplication.
+ */
+import { Tag } from './tag.vo';
+export declare class Tags {
+    private readonly tags;
+    private constructor();
+    /**
+     * Creates a validated tags collection.
+     *
+     * @param values - Array of tag values
+     * @param maxTags - Maximum number of tags (default: 10)
+     * @returns Tags instance
+     * @throws CacheError if validation fails
+     *
+     * @example
+     * ```typescript
+     * const tags = Tags.create(['users', 'product:123']);
+     * const singleTag = Tags.create(['cache']);
+     * ```
+     */
+    static create(values: string[], maxTags?: number): Tags;
+    /**
+     * Creates empty tags collection.
+     */
+    static empty(): Tags;
+    /**
+     * Returns array of tag strings.
+     */
+    toStrings(): string[];
+    /**
+     * Returns array of Tag objects.
+     */
+    toArray(): Tag[];
+    /**
+     * Returns number of tags.
+     */
+    size(): number;
+    /**
+     * Checks if collection contains a specific tag.
+     */
+    has(tag: Tag): boolean;
+    /**
+     * Checks if collection is empty.
+     */
+    isEmpty(): boolean;
+    /**
+     * Iterates over tags.
+     */
+    forEach(callback: (tag: Tag, index: number) => void): void;
+    /**
+     * Maps over tags.
+     */
+    map<T>(callback: (tag: Tag, index: number) => T): T[];
+}
+//# sourceMappingURL=tags.vo.d.ts.map

package/dist/cache/domain/value-objects/tags.vo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.vo.d.ts","sourceRoot":"","sources":["../../../../src/cache/domain/value-objects/tags.vo.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAK/B,qBAAa,IAAI;IACK,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAzC,OAAO;IAEP;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,MAAyB,GAAG,IAAI;IAkBzE;;OAEG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;IAIpB;;OAEG;IACH,SAAS,IAAI,MAAM,EAAE;IAIrB;;OAEG;IACH,OAAO,IAAI,GAAG,EAAE;IAIhB;;OAEG;IACH,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO;IAItB;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAI1D;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC,EAAE;CAGtD"}

package/dist/cache/domain/value-objects/ttl.vo.d.ts

@@ -0,0 +1,58 @@
+/**
+ * TTL (Time To Live) value object.
+ * Validates and normalizes TTL values.
+ */
+export declare class TTL {
+    private readonly seconds;
+    private constructor();
+    /**
+     * Creates a TTL value object.
+     *
+     * @param seconds - TTL in seconds
+     * @param maxTtl - Maximum allowed TTL
+     * @returns TTL instance
+     * @throws CacheError if validation fails
+     */
+    static create(seconds: number, maxTtl?: number): TTL;
+    /**
+     * Creates TTL from milliseconds.
+     *
+     * @param milliseconds - TTL in milliseconds
+     * @param maxTtl - Maximum allowed TTL in seconds
+     * @returns TTL instance
+     */
+    static fromMilliseconds(milliseconds: number, maxTtl?: number): TTL;
+    /**
+     * Returns TTL in seconds.
+     */
+    toSeconds(): number;
+    /**
+     * Returns TTL in milliseconds.
+     */
+    toMilliseconds(): number;
+    /**
+     * Checks if TTL is less than another TTL.
+     */
+    isLessThan(other: TTL): boolean;
+    /**
+     * Checks if TTL is greater than another TTL.
+     */
+    isGreaterThan(other: TTL): boolean;
+    /**
+     * Returns the minimum of two TTLs.
+     */
+    static min(a: TTL, b: TTL): TTL;
+    /**
+     * Returns the maximum of two TTLs.
+     */
+    static max(a: TTL, b: TTL): TTL;
+    /**
+     * Checks equality with another TTL.
+     */
+    equals(other: TTL): boolean;
+    /**
+     * Returns string representation.
+     */
+    toString(): string;
+}
+//# sourceMappingURL=ttl.vo.d.ts.map

package/dist/cache/domain/value-objects/ttl.vo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttl.vo.d.ts","sourceRoot":"","sources":["../../../../src/cache/domain/value-objects/ttl.vo.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,qBAAa,GAAG;IACM,OAAO,CAAC,QAAQ,CAAC,OAAO;IAA5C,OAAO;IAEP;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAgC,GAAG,GAAG;IAiB7E;;;;;;OAMG;IACH,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,GAAE,MAAgC,GAAG,GAAG;IAI5F;;OAEG;IACH,SAAS,IAAI,MAAM;IAInB;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO;IAI/B;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO;IAIlC;;OAEG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,GAAG;IAI/B;;OAEG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,GAAG;IAI/B;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO;IAI3B;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGnB"}

package/dist/cache/infrastructure/adapters/l1-memory-store.adapter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * L1 in-memory cache store implementation.
+ * Supports LRU and LFU eviction policies.
+ */
+import { ICachePluginOptions } from '../../../shared/types';
+import { IL1CacheStore } from '../../application/ports/l1-cache-store.port';
+import { CacheEntry } from '../../domain/value-objects/cache-entry.vo';
+export declare class L1MemoryStoreAdapter implements IL1CacheStore {
+    private readonly options;
+    private readonly cache;
+    private head;
+    private tail;
+    private readonly maxSize;
+    private readonly defaultTtl;
+    private readonly evictionPolicy;
+    private hits;
+    private misses;
+    constructor(options: ICachePluginOptions);
+    get<T>(key: string): Promise<CacheEntry<T> | null>;
+    set<T>(key: string, entry: CacheEntry<T>, ttl?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    size(): Promise<number>;
+    private moveToFront;
+    private removeNode;
+    private evict;
+    private evictLRU;
+    private evictLFU;
+    getStats(): {
+        hits: number;
+        misses: number;
+        size: number;
+    };
+}
+//# sourceMappingURL=l1-memory-store.adapter.d.ts.map

package/dist/cache/infrastructure/adapters/l1-memory-store.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"l1-memory-store.adapter.d.ts","sourceRoot":"","sources":["../../../../src/cache/infrastructure/adapters/l1-memory-store.adapter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,2CAA2C,CAAC;AAWvE,qBACa,oBAAqB,YAAW,aAAa;IAYtD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAX1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0C;IAChE,OAAO,CAAC,IAAI,CAAoC;IAChD,OAAO,CAAC,IAAI,CAAoC;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAC/C,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;gBAIA,OAAO,EAAE,mBAAmB;IAQzC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IA2BlD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2CtE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBlC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAY7B,OAAO,CAAC,WAAW;IAqBnB,OAAO,CAAC,UAAU;IAclB,OAAO,CAAC,KAAK;IAQb,OAAO,CAAC,QAAQ;IAUhB,OAAO,CAAC,QAAQ;IAsBhB,QAAQ,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;CAO3D"}

package/dist/cache/infrastructure/adapters/l2-redis-store.adapter.d.ts

@@ -0,0 +1,41 @@
+/**
+ * L2 Redis cache store implementation.
+ */
+import { IRedisDriver } from '@nestjs-redisx/core';
+import { ICachePluginOptions, ScanResult, SwrEntry } from '../../../shared/types';
+import { IL2CacheStore } from '../../application/ports/l2-cache-store.port';
+import { Serializer } from '../../domain/services/serializer.service';
+import { CacheEntry } from '../../domain/value-objects/cache-entry.vo';
+export declare class L2RedisStoreAdapter implements IL2CacheStore {
+    private readonly driver;
+    private readonly options;
+    private readonly serializer;
+    private readonly keyPrefix;
+    private readonly defaultTtl;
+    private hits;
+    private misses;
+    constructor(driver: IRedisDriver, options: ICachePluginOptions, serializer: Serializer);
+    get<T>(key: string): Promise<CacheEntry<T> | null>;
+    set<T>(key: string, entry: CacheEntry<T>, ttl?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    ttl(key: string): Promise<number>;
+    expire(key: string, ttl: number): Promise<boolean>;
+    scan(pattern: string, count?: number): Promise<ScanResult>;
+    getMany<T>(keys: string[]): Promise<Array<CacheEntry<T> | null>>;
+    setMany<T>(entries: Array<{
+        key: string;
+        entry: CacheEntry<T>;
+        ttl?: number;
+    }>): Promise<void>;
+    private buildKey;
+    private scanKeys;
+    getStats(): Promise<{
+        hits: number;
+        misses: number;
+    }>;
+    getSwr<T>(key: string): Promise<SwrEntry<T> | null>;
+    setSwr<T>(key: string, swrEntry: SwrEntry<T>): Promise<void>;
+}
+//# sourceMappingURL=l2-redis-store.adapter.d.ts.map

package/dist/cache/infrastructure/adapters/l2-redis-store.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"l2-redis-store.adapter.d.ts","sourceRoot":"","sources":["../../../../src/cache/infrastructure/adapters/l2-redis-store.adapter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAgB,YAAY,EAAa,MAAM,qBAAqB,CAAC;AAI5E,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,2CAA2C,CAAC;AAKvE,qBACa,mBAAoB,YAAW,aAAa;IAO/B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU;IARjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;gBAGsB,MAAM,EAAE,YAAY,EACZ,OAAO,EAAE,mBAAmB,EACtC,UAAU,EAAE,UAAU;IAMvD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAmBlD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYtE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsBtB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWlC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUjC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUlD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,MAA2B,GAAG,OAAO,CAAC,UAAU,CAAC;IAiB9E,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAyBhE,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;IAsBpG,OAAO,CAAC,QAAQ;YAIF,QAAQ;IAiBhB,QAAQ,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAOrD,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAmBnD,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAqBnE"}

package/dist/cache.plugin.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Cache plugin for NestJS RedisX.
+ * Provides L1+L2 caching with anti-stampede, SWR, and tag invalidation.
+ */
+import { Provider } from '@nestjs/common';
+import { IRedisXPlugin } from '@nestjs-redisx/core';
+import { ICachePluginOptions } from './shared/types';
+export declare class CachePlugin implements IRedisXPlugin {
+    private readonly options;
+    readonly name = "cache";
+    readonly version = "0.1.0";
+    readonly description = "Advanced caching with L1+L2, anti-stampede, SWR, and tag invalidation";
+    constructor(options?: ICachePluginOptions);
+    getProviders(): Provider[];
+    getExports(): Array<string | symbol | Provider>;
+}
+//# sourceMappingURL=cache.plugin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.plugin.d.ts","sourceRoot":"","sources":["../src/cache.plugin.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAcpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAMrD,qBAAa,WAAY,YAAW,aAAa;IAKnC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,QAAQ,CAAC,IAAI,WAAW;IACxB,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,WAAW,2EAA2E;gBAElE,OAAO,GAAE,mBAAwB;IAE9D,YAAY,IAAI,QAAQ,EAAE;IAsG1B,UAAU,IAAI,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;CAGhD"}