@nest-omni/core 3.1.1-9 → 3.1.2-0

package/cache/cache.module.d.ts

@@ -0,0 +1,26 @@
+import { DynamicModule, OnModuleInit } from '@nestjs/common';
+import type { DataSource } from 'typeorm';
+import type { Redis } from 'ioredis';
+import { CacheService } from './cache.service';
+export declare const CACHE_SERVICE: unique symbol;
+export interface CacheModuleOptions {
+    isGlobal?: boolean;
+    redisClient?: Redis;
+    dataSource?: DataSource;
+    memoryTtl?: number;
+    memoryNamespace?: string;
+    enableCompression?: boolean;
+    compressionThreshold?: number;
+}
+export declare class CacheModule implements OnModuleInit {
+    private readonly cacheService;
+    constructor(cacheService: CacheService);
+    static forRoot(options?: CacheModuleOptions): DynamicModule;
+    static forRootAsync(options: {
+        imports?: any[];
+        inject?: any[];
+        useFactory: (...args: any[]) => Promise<CacheModuleOptions> | CacheModuleOptions;
+        isGlobal?: boolean;
+    }): DynamicModule;
+    onModuleInit(): void;
+}

package/cache/cache.module.js

@@ -0,0 +1,155 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var CacheModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheModule = exports.CACHE_SERVICE = void 0;
+const common_1 = require("@nestjs/common");
+const cache_service_1 = require("./cache.service");
+const cache_warmup_service_1 = require("./cache.warmup.service");
+const cache_metrics_service_1 = require("./cache-metrics.service");
+const cache_serialization_service_1 = require("./cache-serialization.service");
+const dependencies_1 = require("./dependencies");
+const decorators_1 = require("./decorators");
+const providers_1 = require("./providers");
+const cache_constants_1 = require("./cache.constants");
+exports.CACHE_SERVICE = Symbol('CACHE_SERVICE');
+let CacheModule = CacheModule_1 = class CacheModule {
+    constructor(cacheService) {
+        this.cacheService = cacheService;
+    }
+    static forRoot(options = {}) {
+        const { isGlobal = true, redisClient, dataSource, memoryTtl, memoryNamespace, enableCompression = false, compressionThreshold = 1024, } = options;
+        if (dataSource) {
+            dependencies_1.DbDependency.setDataSource(dataSource);
+        }
+        return {
+            module: CacheModule_1,
+            global: isGlobal,
+            providers: [
+                providers_1.ClsCacheProvider,
+                {
+                    provide: providers_1.MemoryCacheProvider,
+                    useValue: new providers_1.MemoryCacheProvider({
+                        ttl: memoryTtl,
+                        namespace: memoryNamespace,
+                    }),
+                },
+                ...(redisClient
+                    ? [
+                        {
+                            provide: providers_1.REDIS_CLIENT,
+                            useValue: redisClient,
+                        },
+                    ]
+                    : []),
+                providers_1.RedisCacheProvider,
+                {
+                    provide: cache_constants_1.CACHE_COMPRESSION_ENABLED,
+                    useValue: enableCompression,
+                },
+                {
+                    provide: cache_constants_1.CACHE_COMPRESSION_THRESHOLD,
+                    useValue: compressionThreshold,
+                },
+                cache_warmup_service_1.CacheWarmupService,
+                cache_metrics_service_1.CacheMetricsService,
+                {
+                    provide: cache_serialization_service_1.CacheSerializationService,
+                    useFactory: () => new cache_serialization_service_1.CacheSerializationService(),
+                },
+                {
+                    provide: exports.CACHE_SERVICE,
+                    useClass: cache_service_1.CacheService,
+                },
+                cache_service_1.CacheService,
+            ],
+            exports: [
+                exports.CACHE_SERVICE,
+                cache_service_1.CacheService,
+                cache_warmup_service_1.CacheWarmupService,
+                cache_metrics_service_1.CacheMetricsService,
+                cache_serialization_service_1.CacheSerializationService,
+            ],
+        };
+    }
+    static forRootAsync(options) {
+        var _a;
+        return {
+            module: CacheModule_1,
+            global: (_a = options.isGlobal) !== null && _a !== void 0 ? _a : true,
+            imports: options.imports || [],
+            providers: [
+                {
+                    provide: 'CACHE_MODULE_OPTIONS',
+                    useFactory: options.useFactory,
+                    inject: options.inject || [],
+                },
+                providers_1.ClsCacheProvider,
+                {
+                    provide: providers_1.MemoryCacheProvider,
+                    useFactory: (moduleOptions) => {
+                        if (moduleOptions.dataSource) {
+                            dependencies_1.DbDependency.setDataSource(moduleOptions.dataSource);
+                        }
+                        return new providers_1.MemoryCacheProvider({
+                            ttl: moduleOptions.memoryTtl,
+                            namespace: moduleOptions.memoryNamespace,
+                        });
+                    },
+                    inject: ['CACHE_MODULE_OPTIONS'],
+                },
+                {
+                    provide: providers_1.REDIS_CLIENT,
+                    useFactory: (moduleOptions) => moduleOptions.redisClient,
+                    inject: ['CACHE_MODULE_OPTIONS'],
+                },
+                providers_1.RedisCacheProvider,
+                cache_warmup_service_1.CacheWarmupService,
+                cache_metrics_service_1.CacheMetricsService,
+                {
+                    provide: cache_serialization_service_1.CacheSerializationService,
+                    useFactory: () => new cache_serialization_service_1.CacheSerializationService(),
+                },
+                {
+                    provide: cache_constants_1.CACHE_COMPRESSION_ENABLED,
+                    useFactory: (moduleOptions) => moduleOptions.enableCompression || false,
+                    inject: ['CACHE_MODULE_OPTIONS'],
+                },
+                {
+                    provide: cache_constants_1.CACHE_COMPRESSION_THRESHOLD,
+                    useFactory: (moduleOptions) => moduleOptions.compressionThreshold || 1024,
+                    inject: ['CACHE_MODULE_OPTIONS'],
+                },
+                {
+                    provide: exports.CACHE_SERVICE,
+                    useClass: cache_service_1.CacheService,
+                },
+                cache_service_1.CacheService,
+            ],
+            exports: [
+                exports.CACHE_SERVICE,
+                cache_service_1.CacheService,
+                cache_warmup_service_1.CacheWarmupService,
+                cache_metrics_service_1.CacheMetricsService,
+                cache_serialization_service_1.CacheSerializationService,
+            ],
+        };
+    }
+    onModuleInit() {
+        (0, decorators_1.setCacheService)(this.cacheService);
+    }
+};
+exports.CacheModule = CacheModule;
+exports.CacheModule = CacheModule = CacheModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({}),
+    __metadata("design:paramtypes", [cache_service_1.CacheService])
+], CacheModule);

package/cache/cache.service.d.ts

@@ -0,0 +1,37 @@
+import type { CacheOptions, CacheStats } from './interfaces';
+import { CacheLayer } from './interfaces';
+import { ClsCacheProvider, MemoryCacheProvider, RedisCacheProvider } from './providers';
+export declare class CacheService {
+    private readonly clsProvider;
+    private readonly memoryProvider;
+    private readonly redisProvider;
+    private readonly enableCompression;
+    private readonly compressionThreshold;
+    private readonly logger;
+    private readonly providers;
+    private readonly stats;
+    constructor(clsProvider: ClsCacheProvider, memoryProvider: MemoryCacheProvider, redisProvider: RedisCacheProvider, enableCompression?: boolean, compressionThreshold?: number);
+    getOrSet<T>(key: string, factory: () => Promise<T>, options?: CacheOptions): Promise<T>;
+    get<T>(key: string, options?: CacheOptions): Promise<T | null>;
+    set<T>(key: string, value: T, options?: CacheOptions | number): Promise<void>;
+    del(key: string | string[], layers?: CacheLayer[]): Promise<void>;
+    deletePattern(pattern: string, layers?: CacheLayer[]): Promise<void>;
+    clear(layers?: CacheLayer[]): Promise<void>;
+    invalidateTags(tags: string[]): Promise<void>;
+    mget<T>(keys: string[], options?: CacheOptions): Promise<(T | null)[]>;
+    mset(items: Array<{
+        key: string;
+        value: any;
+    }>, options?: CacheOptions): Promise<void>;
+    getStats(): CacheStats;
+    resetStats(): void;
+    private setWithOptions;
+    private resolveLayers;
+    private getDefaultLayers;
+    private buildKey;
+    private backfillUpperLayers;
+    private recordHit;
+    private recordMiss;
+    private updateLayerHitRate;
+    private initializeStats;
+}

package/cache/cache.service.js

@@ -0,0 +1,308 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var CacheService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheService = void 0;
+const common_1 = require("@nestjs/common");
+const dependencies_1 = require("./dependencies");
+const interfaces_1 = require("./interfaces");
+const providers_1 = require("./providers");
+const utils_1 = require("./utils");
+const cache_serialization_service_1 = require("./cache-serialization.service");
+const cache_constants_1 = require("./cache.constants");
+let CacheService = CacheService_1 = class CacheService {
+    constructor(clsProvider, memoryProvider, redisProvider, enableCompression = false, compressionThreshold = 1024) {
+        this.clsProvider = clsProvider;
+        this.memoryProvider = memoryProvider;
+        this.redisProvider = redisProvider;
+        this.enableCompression = enableCompression;
+        this.compressionThreshold = compressionThreshold;
+        this.logger = new common_1.Logger(CacheService_1.name);
+        this.providers = new Map();
+        this.stats = {
+            totalGets: 0,
+            hits: 0,
+            misses: 0,
+            hitRate: 0,
+            byLayer: {},
+            totalSets: 0,
+            totalDeletes: 0,
+            totalClears: 0,
+        };
+        this.providers.set(interfaces_1.CacheLayer.CLS, clsProvider);
+        this.providers.set(interfaces_1.CacheLayer.MEMORY, memoryProvider);
+        this.providers.set(interfaces_1.CacheLayer.REDIS, redisProvider);
+        this.initializeStats();
+    }
+    getOrSet(key, factory, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const cached = yield this.get(key, options);
+            if (cached !== null) {
+                return cached;
+            }
+            const value = yield factory();
+            yield this.set(key, value, options);
+            return value;
+        });
+    }
+    get(key, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.stats.totalGets++;
+            const layers = this.resolveLayers(options === null || options === void 0 ? void 0 : options.layers);
+            const fullKey = this.buildKey(key, options === null || options === void 0 ? void 0 : options.namespace);
+            for (let i = 0; i < layers.length; i++) {
+                const layer = layers[i];
+                const provider = this.providers.get(layer);
+                if (!provider) {
+                    continue;
+                }
+                try {
+                    const wrapped = yield provider.get(fullKey);
+                    if (wrapped !== null) {
+                        let value = yield utils_1.DependencyManager.unwrapAndValidate(wrapped, options === null || options === void 0 ? void 0 : options.dependencies);
+                        if (value !== null) {
+                            if (this.enableCompression && Buffer.isBuffer(value)) {
+                                const serializationService = new cache_serialization_service_1.CacheSerializationService();
+                                const decompressed = yield serializationService.deserialize(value);
+                                value = decompressed.data;
+                            }
+                            this.recordHit(layer);
+                            if ((options === null || options === void 0 ? void 0 : options.backfill) !== false && i > 0) {
+                                yield this.backfillUpperLayers(fullKey, wrapped, layers.slice(0, i), options === null || options === void 0 ? void 0 : options.ttl);
+                            }
+                            return value;
+                        }
+                        yield provider.delete(fullKey);
+                    }
+                }
+                catch (error) {
+                    this.logger.warn(`Failed to get from ${layer} cache: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            this.recordMiss();
+            return null;
+        });
+    }
+    set(key, value, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (typeof options === 'number') {
+                return this.setWithOptions(key, value, { ttl: options });
+            }
+            else {
+                return this.setWithOptions(key, value, options);
+            }
+        });
+    }
+    del(key, layers) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.stats.totalDeletes++;
+            const targetLayers = layers || this.getDefaultLayers();
+            const keys = Array.isArray(key) ? key : [key];
+            const promises = targetLayers.map((layer) => __awaiter(this, void 0, void 0, function* () {
+                const provider = this.providers.get(layer);
+                if (!provider) {
+                    return;
+                }
+                try {
+                    yield provider.delete(keys);
+                }
+                catch (error) {
+                    this.logger.warn(`Failed to delete from ${layer} cache: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }));
+            yield Promise.all(promises);
+        });
+    }
+    deletePattern(pattern, layers) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const targetLayers = layers || [interfaces_1.CacheLayer.MEMORY, interfaces_1.CacheLayer.REDIS];
+            const promises = targetLayers.map((layer) => __awaiter(this, void 0, void 0, function* () {
+                const provider = this.providers.get(layer);
+                if (!provider || !provider.deletePattern) {
+                    return;
+                }
+                try {
+                    yield provider.deletePattern(pattern);
+                }
+                catch (error) {
+                    this.logger.warn(`Failed to delete pattern from ${layer} cache: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }));
+            yield Promise.all(promises);
+        });
+    }
+    clear(layers) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.stats.totalClears++;
+            const targetLayers = layers || this.getDefaultLayers();
+            const promises = targetLayers.map((layer) => __awaiter(this, void 0, void 0, function* () {
+                const provider = this.providers.get(layer);
+                if (!provider) {
+                    return;
+                }
+                try {
+                    yield provider.clear();
+                }
+                catch (error) {
+                    this.logger.warn(`Failed to clear ${layer} cache: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }));
+            yield Promise.all(promises);
+        });
+    }
+    invalidateTags(tags) {
+        return __awaiter(this, void 0, void 0, function* () {
+            dependencies_1.TagDependency.invalidateTags(tags);
+            this.logger.debug(`Invalidated tags: ${tags.join(', ')}`);
+        });
+    }
+    mget(keys, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const promises = keys.map((key) => this.get(key, options));
+            return Promise.all(promises);
+        });
+    }
+    mset(items, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const promises = items.map((item) => this.set(item.key, item.value, options));
+            yield Promise.all(promises);
+        });
+    }
+    getStats() {
+        return Object.assign(Object.assign({}, this.stats), { hitRate: this.stats.totalGets > 0 ? this.stats.hits / this.stats.totalGets : 0 });
+    }
+    resetStats() {
+        this.stats.totalGets = 0;
+        this.stats.hits = 0;
+        this.stats.misses = 0;
+        this.stats.hitRate = 0;
+        this.stats.totalSets = 0;
+        this.stats.totalDeletes = 0;
+        this.stats.totalClears = 0;
+        this.initializeStats();
+    }
+    setWithOptions(key, value, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.stats.totalSets++;
+            if ((options === null || options === void 0 ? void 0 : options.condition) && !(yield Promise.resolve(options.condition()))) {
+                return;
+            }
+            const layers = this.resolveLayers(options === null || options === void 0 ? void 0 : options.layers);
+            const fullKey = this.buildKey(key, options === null || options === void 0 ? void 0 : options.namespace);
+            let processedValue = value;
+            if (this.enableCompression &&
+                value !== null &&
+                value !== undefined &&
+                JSON.stringify(value).length >= this.compressionThreshold) {
+                const serializationService = new cache_serialization_service_1.CacheSerializationService();
+                const compressed = yield serializationService.serialize(value, {
+                    compress: true,
+                    compressThreshold: this.compressionThreshold,
+                });
+                processedValue = compressed.data;
+            }
+            const wrapped = yield utils_1.DependencyManager.wrapWithDependencies(processedValue, options === null || options === void 0 ? void 0 : options.dependencies);
+            const promises = layers.map((layer) => __awaiter(this, void 0, void 0, function* () {
+                const provider = this.providers.get(layer);
+                if (!provider) {
+                    return;
+                }
+                try {
+                    yield provider.set(fullKey, wrapped, options === null || options === void 0 ? void 0 : options.ttl);
+                }
+                catch (error) {
+                    this.logger.warn(`Failed to set in ${layer} cache: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }));
+            yield Promise.all(promises);
+        });
+    }
+    resolveLayers(layers) {
+        if (layers && layers.length > 0) {
+            return layers;
+        }
+        return this.getDefaultLayers();
+    }
+    getDefaultLayers() {
+        return [interfaces_1.CacheLayer.CLS, interfaces_1.CacheLayer.MEMORY, interfaces_1.CacheLayer.REDIS];
+    }
+    buildKey(key, namespace) {
+        if (namespace) {
+            return `${namespace}:${key}`;
+        }
+        return key;
+    }
+    backfillUpperLayers(key, value, layers, ttl) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const promises = layers.map((layer) => __awaiter(this, void 0, void 0, function* () {
+                const provider = this.providers.get(layer);
+                if (!provider) {
+                    return;
+                }
+                try {
+                    yield provider.set(key, value, ttl);
+                }
+                catch (error) {
+                    this.logger.debug(`Failed to backfill ${layer} cache: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }));
+            yield Promise.all(promises);
+        });
+    }
+    recordHit(layer) {
+        this.stats.hits++;
+        if (!this.stats.byLayer[layer]) {
+            this.stats.byLayer[layer] = { hits: 0, misses: 0, hitRate: 0 };
+        }
+        this.stats.byLayer[layer].hits++;
+        this.updateLayerHitRate(layer);
+    }
+    recordMiss() {
+        this.stats.misses++;
+    }
+    updateLayerHitRate(layer) {
+        const layerStats = this.stats.byLayer[layer];
+        if (layerStats) {
+            const total = layerStats.hits + layerStats.misses;
+            layerStats.hitRate = total > 0 ? layerStats.hits / total : 0;
+        }
+    }
+    initializeStats() {
+        for (const layer of [interfaces_1.CacheLayer.CLS, interfaces_1.CacheLayer.MEMORY, interfaces_1.CacheLayer.REDIS]) {
+            if (!this.stats.byLayer[layer]) {
+                this.stats.byLayer[layer] = { hits: 0, misses: 0, hitRate: 0 };
+            }
+        }
+    }
+};
+exports.CacheService = CacheService;
+exports.CacheService = CacheService = CacheService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(3, (0, common_1.Optional)()),
+    __param(3, (0, common_1.Inject)(cache_constants_1.CACHE_COMPRESSION_ENABLED)),
+    __param(4, (0, common_1.Optional)()),
+    __param(4, (0, common_1.Inject)(cache_constants_1.CACHE_COMPRESSION_THRESHOLD)),
+    __metadata("design:paramtypes", [providers_1.ClsCacheProvider,
+        providers_1.MemoryCacheProvider,
+        providers_1.RedisCacheProvider, Boolean, Number])
+], CacheService);

package/cache/cache.warmup.service.d.ts

@@ -0,0 +1,34 @@
+import { CacheService } from './cache.service';
+export interface CacheWarmupConfig {
+    name: string;
+    dataProvider: () => Promise<any> | any;
+    key: string | ((data: any) => string);
+    ttl?: number;
+    layers?: string[];
+    batchSize?: number;
+    critical?: boolean;
+}
+export interface CacheWarmupResult {
+    name: string;
+    success: boolean;
+    itemCount: number;
+    duration: number;
+    errors: string[];
+}
+export declare class CacheWarmupService {
+    private readonly cacheService;
+    private readonly logger;
+    private warmupConfigs;
+    constructor(cacheService: CacheService);
+    registerWarmup(groupName: string, configs: CacheWarmupConfig[]): void;
+    warmupGroup(groupName: string): Promise<CacheWarmupResult[]>;
+    warmupAll(): Promise<Map<string, CacheWarmupResult[]>>;
+    getWarmupStats(): {
+        totalGroups: number;
+        totalTasks: number;
+        taskDetails: any[];
+    };
+    removeWarmupGroup(groupName: string): boolean;
+    clearWarmupConfigs(): void;
+    private executeWarmupTask;
+}