@nestjs-redisx/cache 1.0.0

package/dist/serializers/json.serializer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * JSON serializer for cache values.
+ *
+ * Uses native JSON.stringify/parse for serialization.
+ * Best for human-readable data and compatibility.
+ *
+ * @example
+ * ```typescript
+ * const serializer = new JsonSerializer();
+ *
+ * const data = { id: 1, name: 'John' };
+ * const serialized = serializer.serialize(data);
+ * // '{"id":1,"name":"John"}'
+ *
+ * const deserialized = serializer.deserialize<User>(serialized);
+ * // { id: 1, name: 'John' }
+ * ```
+ */
+import { ISerializer } from './serializer.interface';
+export declare class JsonSerializer implements ISerializer {
+    /**
+     * Serializes value to JSON string.
+     *
+     * @param value - Value to serialize
+     * @returns JSON string
+     * @throws SerializationError if serialization fails
+     */
+    serialize<T>(value: T): string;
+    /**
+     * Deserializes JSON string back to value.
+     *
+     * @param data - JSON string or buffer
+     * @returns Deserialized value
+     * @throws SerializationError if deserialization fails
+     */
+    deserialize<T>(data: string | Buffer): T;
+    /**
+     * Safely tries to deserialize, returns null on error.
+     *
+     * @param data - JSON string or buffer
+     * @returns Deserialized value or null
+     */
+    tryDeserialize<T>(data: string | Buffer): T | null;
+    /**
+     * Gets content type for JSON.
+     *
+     * @returns Content type string
+     */
+    getContentType(): string;
+}
+//# sourceMappingURL=json.serializer.d.ts.map

package/dist/serializers/json.serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.serializer.d.ts","sourceRoot":"","sources":["../../src/serializers/json.serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGrD,qBAAa,cAAe,YAAW,WAAW;IAChD;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM;IAQ9B;;;;;;OAMG;IACH,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC;IASxC;;;;;OAKG;IACH,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,GAAG,IAAI;IAQlD;;;;OAIG;IACH,cAAc,IAAI,MAAM;CAGzB"}

package/dist/serializers/msgpack.serializer.d.ts

@@ -0,0 +1,67 @@
+/**
+ * MessagePack serializer for cache values.
+ *
+ * Uses msgpackr for binary serialization.
+ * More compact and faster than JSON, but requires msgpackr package.
+ *
+ * Install: npm install msgpackr
+ *
+ * @example
+ * ```typescript
+ * const serializer = new MsgpackSerializer();
+ *
+ * const data = { id: 1, name: 'John', tags: ['user', 'active'] };
+ * const serialized = serializer.serialize(data);
+ * // Buffer<...> (binary data, ~40% smaller than JSON)
+ *
+ * const deserialized = serializer.deserialize<User>(serialized);
+ * // { id: 1, name: 'John', tags: ['user', 'active'] }
+ * ```
+ */
+import { ISerializer } from './serializer.interface';
+export declare class MsgpackSerializer implements ISerializer {
+    private encoder;
+    private decoder;
+    constructor();
+    /**
+     * Serializes value to MessagePack buffer.
+     *
+     * @param value - Value to serialize
+     * @returns MessagePack buffer
+     * @throws SerializationError if serialization fails
+     */
+    serialize<T>(value: T): Buffer;
+    /**
+     * Deserializes MessagePack buffer back to value.
+     *
+     * @param data - MessagePack buffer or string
+     * @returns Deserialized value
+     * @throws SerializationError if deserialization fails
+     */
+    deserialize<T>(data: string | Buffer): T;
+    /**
+     * Safely tries to deserialize, returns null on error.
+     *
+     * @param data - MessagePack buffer or string
+     * @returns Deserialized value or null
+     */
+    tryDeserialize<T>(data: string | Buffer): T | null;
+    /**
+     * Gets content type for MessagePack.
+     *
+     * @returns Content type string
+     */
+    getContentType(): string;
+    /**
+     * Compares serialized size with JSON.
+     *
+     * @param value - Value to compare
+     * @returns Object with sizes and compression ratio
+     */
+    compareWithJson<T>(value: T): {
+        jsonSize: number;
+        msgpackSize: number;
+        compressionRatio: number;
+    };
+}
+//# sourceMappingURL=msgpack.serializer.d.ts.map

package/dist/serializers/msgpack.serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"msgpack.serializer.d.ts","sourceRoot":"","sources":["../../src/serializers/msgpack.serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAiBrD,qBAAa,iBAAkB,YAAW,WAAW;IACnD,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,OAAO,CAAkB;;IAmBjC;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM;IAQ9B;;;;;;OAMG;IACH,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC;IASxC;;;;;OAKG;IACH,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,GAAG,IAAI;IAQlD;;;;OAIG;IACH,cAAc,IAAI,MAAM;IAIxB;;;;;OAKG;IACH,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG;QAC5B,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,MAAM,CAAC;KAC1B;CAUF"}

package/dist/serializers/serializer.interface.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Serializer interface for cache value serialization.
+ * Defines how values are converted to/from storage format.
+ */
+export interface ISerializer {
+    /**
+     * Serializes a value to string or Buffer.
+     *
+     * @param value - Value to serialize
+     * @returns Serialized data
+     * @throws Error if serialization fails
+     */
+    serialize<T>(value: T): string | Buffer;
+    /**
+     * Deserializes data back to original value.
+     *
+     * @param data - Serialized data
+     * @returns Deserialized value
+     * @throws Error if deserialization fails
+     */
+    deserialize<T>(data: string | Buffer): T;
+    /**
+     * Safely tries to deserialize, returns null on error.
+     *
+     * @param data - Serialized data
+     * @returns Deserialized value or null
+     */
+    tryDeserialize<T>(data: string | Buffer): T | null;
+    /**
+     * Gets the content type identifier for this serializer.
+     *
+     * @returns Content type string (e.g., 'application/json', 'application/msgpack')
+     */
+    getContentType(): string;
+}
+//# sourceMappingURL=serializer.interface.d.ts.map

package/dist/serializers/serializer.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.interface.d.ts","sourceRoot":"","sources":["../../src/serializers/serializer.interface.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,GAAG,MAAM,CAAC;IAExC;;;;;;OAMG;IACH,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,CAAC;IAEzC;;;;;OAKG;IACH,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC;IAEnD;;;;OAIG;IACH,cAAc,IAAI,MAAM,CAAC;CAC1B"}

package/dist/shared/constants/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Shared constants for Cache plugin.
+ */
+/**
+ * Injection tokens.
+ */
+export declare const CACHE_PLUGIN_OPTIONS: unique symbol;
+export declare const CACHE_SERVICE: unique symbol;
+export declare const L1_CACHE_STORE: unique symbol;
+export declare const L2_CACHE_STORE: unique symbol;
+export declare const STAMPEDE_PROTECTION: unique symbol;
+export declare const TAG_INDEX: unique symbol;
+export declare const SWR_MANAGER: unique symbol;
+export declare const TAG_CONFIG: unique symbol;
+export declare const SERIALIZER: unique symbol;
+export declare const INVALIDATION_REGISTRY: unique symbol;
+export declare const EVENT_INVALIDATION_SERVICE: unique symbol;
+export declare const LUA_SCRIPT_LOADER: unique symbol;
+export declare const INVALIDATION_RULES_INIT: unique symbol;
+export declare const AMQP_CONNECTION: unique symbol;
+/**
+ * Metadata keys for decorators.
+ */
+export declare const CACHE_OPTIONS_KEY = "cache:options";
+export declare const INVALIDATE_TAGS_KEY = "cache:invalidate:tags";
+/**
+ * Default configuration values.
+ */
+export declare const DEFAULT_CACHE_CONFIG: {
+    readonly l1: {
+        readonly enabled: true;
+        readonly maxSize: 1000;
+        readonly ttl: 60;
+        readonly evictionPolicy: "lru";
+    };
+    readonly l2: {
+        readonly enabled: true;
+        readonly defaultTtl: 3600;
+        readonly maxTtl: 86400;
+        readonly keyPrefix: "cache:";
+        readonly clientName: "default";
+    };
+    readonly stampede: {
+        readonly enabled: true;
+        readonly lockTimeout: 5000;
+        readonly waitTimeout: 10000;
+        readonly fallback: "load";
+    };
+    readonly swr: {
+        readonly enabled: false;
+        readonly defaultStaleTime: 60;
+    };
+    readonly tags: {
+        readonly enabled: true;
+        readonly indexPrefix: "_tag:";
+        readonly maxTagsPerKey: 10;
+    };
+    readonly warmup: {
+        readonly enabled: false;
+        readonly concurrency: 10;
+    };
+    readonly keys: {
+        readonly maxLength: 1024;
+        readonly version: "v1";
+        readonly separator: ":";
+    };
+    readonly invalidation: {
+        readonly enabled: true;
+        readonly source: "internal";
+        readonly deduplicationTtl: 60;
+    };
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/shared/constants/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/constants/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB,eAAqC,CAAC;AACvE,eAAO,MAAM,aAAa,eAA8B,CAAC;AACzD,eAAO,MAAM,cAAc,eAA+B,CAAC;AAC3D,eAAO,MAAM,cAAc,eAA+B,CAAC;AAC3D,eAAO,MAAM,mBAAmB,eAAoC,CAAC;AACrE,eAAO,MAAM,SAAS,eAA0B,CAAC;AACjD,eAAO,MAAM,WAAW,eAA4B,CAAC;AACrD,eAAO,MAAM,UAAU,eAA2B,CAAC;AACnD,eAAO,MAAM,UAAU,eAA2B,CAAC;AACnD,eAAO,MAAM,qBAAqB,eAAsC,CAAC;AACzE,eAAO,MAAM,0BAA0B,eAA2C,CAAC;AACnF,eAAO,MAAM,iBAAiB,eAAkC,CAAC;AACjE,eAAO,MAAM,uBAAuB,eAAwC,CAAC;AAC7E,eAAO,MAAM,eAAe,eAAgC,CAAC;AAE7D;;GAEG;AACH,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AACjD,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAE3D;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CvB,CAAC"}

package/dist/shared/errors/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Cache plugin error classes.
+ */
+import { RedisXError, ErrorCode } from '@nestjs-redisx/core';
+/**
+ * Base error for cache operations.
+ */
+export declare class CacheError extends RedisXError {
+    constructor(message: string, code?: ErrorCode, cause?: Error);
+}
+/**
+ * Error for invalid cache keys.
+ */
+export declare class CacheKeyError extends CacheError {
+    readonly key: string;
+    constructor(key: string, message: string);
+}
+/**
+ * Error for serialization failures.
+ */
+export declare class SerializationError extends CacheError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error for loader function failures.
+ */
+export declare class LoaderError extends CacheError {
+    readonly key: string;
+    constructor(key: string, cause: Error);
+}
+/**
+ * Error for stampede protection timeout.
+ */
+export declare class StampedeError extends CacheError {
+    readonly key: string;
+    readonly timeout: number;
+    constructor(key: string, timeout: number);
+}
+/**
+ * Error for tag invalidation failures.
+ */
+export declare class TagInvalidationError extends CacheError {
+    readonly tag: string;
+    constructor(tag: string, message: string, cause?: Error);
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/shared/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/errors/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;GAEG;AACH,qBAAa,UAAW,SAAQ,WAAW;gBAC7B,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,SAAsC,EAAE,KAAK,CAAC,EAAE,KAAK;CAIzF;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,UAAU;aAEzB,GAAG,EAAE,MAAM;gBAAX,GAAG,EAAE,MAAM,EAC3B,OAAO,EAAE,MAAM;CAKlB;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,UAAU;gBACpC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAI3C;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,UAAU;aAEvB,GAAG,EAAE,MAAM;gBAAX,GAAG,EAAE,MAAM,EAC3B,KAAK,EAAE,KAAK;CAKf;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,UAAU;aAEzB,GAAG,EAAE,MAAM;aACX,OAAO,EAAE,MAAM;gBADf,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM;CAKlC;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,UAAU;aAEhC,GAAG,EAAE,MAAM;gBAAX,GAAG,EAAE,MAAM,EAC3B,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,KAAK;CAKhB"}

package/dist/shared/types/context-provider.interface.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Interface for context providers (CLS, AsyncLocalStorage, custom).
+ * Users implement this to integrate their own context management.
+ *
+ * This is an adapter interface - no external dependencies required.
+ * Users can integrate any context management solution by implementing this interface.
+ *
+ * @example nestjs-cls integration
+ * ```typescript
+ * import { ClsService } from 'nestjs-cls';
+ *
+ * const provider: IContextProvider = {
+ *   get: (key) => clsService.get(key),
+ * };
+ * ```
+ *
+ * @example AsyncLocalStorage integration
+ * ```typescript
+ * import { AsyncLocalStorage } from 'async_hooks';
+ *
+ * const als = new AsyncLocalStorage<Map<string, any>>();
+ * const provider: IContextProvider = {
+ *   get: (key) => als.getStore()?.get(key),
+ * };
+ * ```
+ *
+ * @example Custom context integration
+ * ```typescript
+ * class MyContextManager {
+ *   private context = new Map<string, any>();
+ *
+ *   get(key: string) {
+ *     return this.context.get(key);
+ *   }
+ * }
+ *
+ * const manager = new MyContextManager();
+ * const provider: IContextProvider = {
+ *   get: (key) => manager.get(key),
+ * };
+ * ```
+ */
+export interface IContextProvider {
+    /**
+     * Get value from context by key.
+     *
+     * @param key - Context key to retrieve
+     * @returns Value from context or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const tenantId = provider.get<string>('tenantId');
+     * const userId = provider.get<number>('userId');
+     * ```
+     */
+    get<T = unknown>(key: string): T | undefined;
+}
+//# sourceMappingURL=context-provider.interface.d.ts.map

package/dist/shared/types/context-provider.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-provider.interface.d.ts","sourceRoot":"","sources":["../../../src/shared/types/context-provider.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;CAC9C"}

package/dist/shared/types/index.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Shared types for Cache plugin.
+ */
+export type { IContextProvider } from './context-provider.interface';
+/**
+ * Cache plugin configuration.
+ */
+export interface ICachePluginOptions {
+    /** Make module global */
+    isGlobal?: boolean;
+    /** L1 in-memory cache config */
+    l1?: {
+        enabled?: boolean;
+        maxSize?: number;
+        ttl?: number;
+        evictionPolicy?: 'lru' | 'lfu';
+    };
+    /** L2 Redis cache config */
+    l2?: {
+        enabled?: boolean;
+        defaultTtl?: number;
+        maxTtl?: number;
+        keyPrefix?: string;
+        clientName?: string;
+    };
+    /** Stampede protection config */
+    stampede?: {
+        enabled?: boolean;
+        lockTimeout?: number;
+        waitTimeout?: number;
+        fallback?: 'load' | 'error' | 'null';
+    };
+    /** Stale-while-revalidate config */
+    swr?: {
+        enabled?: boolean;
+        defaultStaleTime?: number;
+    };
+    /** Tag invalidation config */
+    tags?: {
+        enabled?: boolean;
+        indexPrefix?: string;
+        maxTagsPerKey?: number;
+        ttl?: number;
+    };
+    /** Cache warming config */
+    warmup?: {
+        enabled?: boolean;
+        keys?: IWarmupKey[];
+        concurrency?: number;
+    };
+    /** Key config */
+    keys?: {
+        maxLength?: number;
+        version?: string;
+        separator?: string;
+    };
+    /** Event-driven invalidation config */
+    invalidation?: IInvalidationOptions;
+    /**
+     * Context provider for automatic key enrichment.
+     * Allows integrating CLS, AsyncLocalStorage, or custom context management.
+     *
+     * @example nestjs-cls
+     * ```typescript
+     * import { ClsService } from 'nestjs-cls';
+     *
+     * contextProvider: {
+     *   get: (key) => clsService.get(key),
+     * }
+     * ```
+     *
+     * @example AsyncLocalStorage
+     * ```typescript
+     * const als = new AsyncLocalStorage<Map<string, any>>();
+     * contextProvider: {
+     *   get: (key) => als.getStore()?.get(key),
+     * }
+     * ```
+     */
+    contextProvider?: import('./context-provider.interface').IContextProvider;
+    /**
+     * Keys to extract from context provider and append to cache keys.
+     * These keys will be automatically added to all cache keys unless skipContext is set.
+     *
+     * @example ['tenantId', 'userId', 'locale']
+     * @default []
+     */
+    contextKeys?: string[];
+}
+/**
+ * Warmup key configuration.
+ */
+export interface IWarmupKey {
+    key: string;
+    loader: () => Promise<unknown>;
+    ttl?: number;
+    tags?: string[];
+}
+/**
+ * Cache set options.
+ */
+export interface ICacheSetOptions {
+    ttl?: number;
+    tags?: string[];
+    strategy?: 'l1-only' | 'l2-only' | 'l1-l2';
+    varyBy?: Record<string, string>;
+}
+/**
+ * Cache getOrSet options.
+ */
+export interface ICacheGetOrSetOptions extends ICacheSetOptions {
+    swr?: {
+        enabled?: boolean;
+        staleTime?: number;
+    };
+    skipStampede?: boolean;
+}
+/**
+ * Cache statistics.
+ */
+export interface ICacheStats {
+    l1: {
+        hits: number;
+        misses: number;
+        size: number;
+    };
+    l2: {
+        hits: number;
+        misses: number;
+    };
+    stampedePrevented: number;
+}
+/**
+ * SWR entry result with metadata.
+ */
+export interface ISwrEntry<T> {
+    /** The cached value */
+    value: T;
+    /** Timestamp when value was cached (ms) */
+    cachedAt: number;
+    /** Timestamp when value becomes stale (ms) */
+    staleAt: number;
+    /** Timestamp when value expires completely (ms) */
+    expiresAt: number;
+}
+/**
+ * Stampede execution result.
+ */
+export interface IStampedeResult<T> {
+    value: T;
+    cached: boolean;
+    waited: boolean;
+}
+/**
+ * Stampede statistics.
+ */
+export interface IStampedeStats {
+    activeFlights: number;
+    totalWaiters: number;
+    oldestFlight: number;
+    prevented: number;
+}
+/**
+ * Stampede options.
+ */
+export interface IStampedeOptions {
+    lockTimeout: number;
+    waitTimeout: number;
+}
+/**
+ * Scan result.
+ */
+export interface IScanResult {
+    cursor: string;
+    keys: string[];
+}
+/**
+ * Event-driven invalidation options.
+ */
+export interface IInvalidationOptions {
+    /**
+     * Enable event-driven invalidation.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Event source type.
+     * @default 'internal'
+     */
+    source?: 'internal' | 'amqp' | 'custom';
+    /**
+     * AMQP configuration (if source = 'amqp').
+     */
+    amqp?: {
+        /**
+         * Exchange to listen for invalidation events.
+         * @default 'cache.invalidation'
+         */
+        exchange?: string;
+        /**
+         * Queue name for this service.
+         * @default '{serviceName}.cache.invalidation'
+         */
+        queue?: string;
+        /**
+         * Routing key patterns to subscribe.
+         * @default ['#'] (all events)
+         */
+        routingKeys?: string[];
+    };
+    /**
+     * Static invalidation rules.
+     * Can also be registered dynamically via InvalidationRegistry.
+     */
+    rules?: IInvalidationRuleProps[];
+    /**
+     * Default TTL for tracking processed events (dedup).
+     * @default 60 (seconds)
+     */
+    deduplicationTtl?: number;
+}
+/**
+ * Invalidation rule properties.
+ */
+export interface IInvalidationRuleProps {
+    /**
+     * Event pattern to match.
+     * Supports wildcards: 'user.*', '*.updated', '#'
+     */
+    event: string;
+    /**
+     * Tags to invalidate.
+     * Supports templates: 'user:{userId}', 'tenant:{payload.tenantId}'
+     */
+    tags?: string[];
+    /**
+     * Keys to invalidate directly.
+     * Supports templates: 'user:{userId}:profile'
+     */
+    keys?: string[];
+    /**
+     * Condition for invalidation.
+     */
+    condition?: (payload: unknown) => boolean;
+    /**
+     * Priority (higher = processed first).
+     * @default 0
+     */
+    priority?: number;
+}
+export type CacheSetOptions = ICacheSetOptions;
+export type CacheGetOrSetOptions = ICacheGetOrSetOptions;
+export type CacheStats = ICacheStats;
+export type SwrEntry<T = unknown> = ISwrEntry<T>;
+export type StampedeResult<T = unknown> = IStampedeResult<T>;
+export type StampedeStats = IStampedeStats;
+export type StampedeOptions = IStampedeOptions;
+export type ScanResult = IScanResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/shared/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,yBAAyB;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,gCAAgC;IAChC,EAAE,CAAC,EAAE;QACH,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,cAAc,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;KAChC,CAAC;IAEF,4BAA4B;IAC5B,EAAE,CAAC,EAAE;QACH,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IAEF,iCAAiC;IACjC,QAAQ,CAAC,EAAE;QACT,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;KACtC,CAAC;IAEF,oCAAoC;IACpC,GAAG,CAAC,EAAE;QACJ,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;IAEF,8BAA8B;IAC9B,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;IAEF,2BAA2B;IAC3B,MAAM,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,IAAI,CAAC,EAAE,UAAU,EAAE,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IAEF,iBAAiB;IACjB,IAAI,CAAC,EAAE;QACL,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IAEF,uCAAuC;IACvC,YAAY,CAAC,EAAE,oBAAoB,CAAC;IAEpC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,eAAe,CAAC,EAAE,OAAO,8BAA8B,EAAE,gBAAgB,CAAC;IAE1E;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D,GAAG,CAAC,EAAE;QACJ,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE;QACF,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,EAAE,EAAE;QACF,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,uBAAuB;IACvB,KAAK,EAAE,CAAC,CAAC;IAET,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IAEjB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAEhB,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,KAAK,EAAE,CAAC,CAAC;IACT,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;IAExC;;OAEG;IACH,IAAI,CAAC,EAAE;QACL;;;WAGG;QACH,QAAQ,CAAC,EAAE,MAAM,CAAC;QAElB;;;WAGG;QACH,KAAK,CAAC,EAAE,MAAM,CAAC;QAEf;;;WAGG;QACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;KACxB,CAAC;IAEF;;;OAGG;IACH,KAAK,CAAC,EAAE,sBAAsB,EAAE,CAAC;IAEjC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;IAE1C;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,eAAe,GAAG,gBAAgB,CAAC;AAC/C,MAAM,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AACzD,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC;AACrC,MAAM,MAAM,QAAQ,CAAC,CAAC,GAAG,OAAO,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC;AACjD,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,OAAO,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC;AAC7D,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC;AAC3C,MAAM,MAAM,eAAe,GAAG,gBAAgB,CAAC;AAC/C,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC"}

package/dist/stampede/application/ports/stampede-protection.port.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Stampede protection service interface.
+ */
+import { IStampedeResult, IStampedeStats } from '../../../shared/types';
+export interface IStampedeProtection {
+    /**
+     * Executes loader with stampede protection.
+     * Only one concurrent execution per key is allowed within the same process.
+     * Uses distributed Redis lock for cross-process protection.
+     *
+     * @param key - Unique key for the operation
+     * @param loader - Function to execute
+     * @returns Result with cached/waited flags
+     */
+    protect<T>(key: string, loader: () => Promise<T>): Promise<IStampedeResult<T>>;
+    /**
+     * Cancels an in-flight request for a key.
+     *
+     * @param key - Key to cancel
+     */
+    clearKey(key: string): Promise<void>;
+    /**
+     * Cancels all in-flight requests.
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Gets stampede protection statistics.
+     *
+     * @returns Stats with active flights, waiters, and prevented count
+     */
+    getStats(): IStampedeStats;
+}
+//# sourceMappingURL=stampede-protection.port.d.ts.map

package/dist/stampede/application/ports/stampede-protection.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stampede-protection.port.d.ts","sourceRoot":"","sources":["../../../../src/stampede/application/ports/stampede-protection.port.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAExE,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAE/E;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErC;;OAEG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;;;OAIG;IACH,QAAQ,IAAI,cAAc,CAAC;CAC5B"}