@nest-omni/core 3.1.1-11 → 3.1.1-13

package/cache/cache-metrics.service.d.ts

@@ -0,0 +1,83 @@
+import { EventEmitter } from 'events';
+export interface CacheOperationRecord {
+    type: 'get' | 'set' | 'delete' | 'clear';
+    layer: string;
+    hit: boolean;
+    latency: number;
+    error?: string;
+    key?: string;
+    timestamp: Date;
+}
+export interface CacheMetrics {
+    totalOperations: number;
+    hits: number;
+    misses: number;
+    hitRate: number;
+    avgLatency: number;
+    minLatency: number;
+    maxLatency: number;
+    p95Latency: number;
+    p99Latency: number;
+    gets: number;
+    sets: number;
+    deletes: number;
+    clears: number;
+    totalKeys: number;
+    totalSize: number;
+    errors: number;
+    errorRate: number;
+    layerMetrics: {
+        cls: {
+            hits: number;
+            misses: number;
+            avgLatency: number;
+        };
+        memory: {
+            hits: number;
+            misses: number;
+            avgLatency: number;
+            size: number;
+        };
+        redis: {
+            hits: number;
+            misses: number;
+            avgLatency: number;
+        };
+    };
+    timeWindow: {
+        start: Date;
+        end: Date;
+        duration: number;
+    };
+}
+export declare class CacheMetricsService extends EventEmitter {
+    private readonly logger;
+    private readonly operations;
+    private readonly maxOperations;
+    private readonly maxAge;
+    constructor();
+    recordOperation(type: 'get' | 'set' | 'delete' | 'clear', layer: string, hit: boolean, latency: number, error?: string, key?: string): void;
+    getMetrics(timeWindowMs?: number): CacheMetrics;
+    getSnapshot(): Partial<CacheMetrics>;
+    getSlowOperations(limit?: number): CacheOperationRecord[];
+    getMostAccessedKeys(limit?: number): {
+        key: string;
+        count: number;
+        avgLatency: number;
+    }[];
+    getErrorBreakdown(): {
+        error: string;
+        count: number;
+        lastOccurrence: Date;
+    }[];
+    resetMetrics(): void;
+    exportMetrics(format?: 'prometheus' | 'json'): string;
+    private cleanupOldRecords;
+    private createEmptyMetrics;
+    private calculateLayerMetrics;
+    private average;
+    private percentile;
+    private getUniqueKeyCount;
+    private estimateTotalSize;
+    private toPrometheusFormat;
+}

package/cache/cache-metrics.service.js

@@ -0,0 +1,298 @@
+"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 CacheMetricsService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheMetricsService = void 0;
+const common_1 = require("@nestjs/common");
+const events_1 = require("events");
+let CacheMetricsService = CacheMetricsService_1 = class CacheMetricsService extends events_1.EventEmitter {
+    constructor() {
+        super();
+        this.logger = new common_1.Logger(CacheMetricsService_1.name);
+        this.operations = [];
+        this.maxOperations = 10000;
+        this.maxAge = 3600000;
+        setInterval(() => this.cleanupOldRecords(), 60000);
+    }
+    recordOperation(type, layer, hit, latency, error, key) {
+        const record = {
+            type,
+            layer,
+            hit,
+            latency,
+            error,
+            key,
+            timestamp: new Date(),
+        };
+        this.operations.push(record);
+        if (this.operations.length > this.maxOperations) {
+            this.operations.splice(0, this.operations.length - this.maxOperations);
+        }
+        this.emit('operation', record);
+        if (error) {
+            this.logger.warn(`Cache operation error: ${type} on ${layer} - ${error}`);
+        }
+    }
+    getMetrics(timeWindowMs = 300000) {
+        const endTime = new Date();
+        const startTime = new Date(endTime.getTime() - timeWindowMs);
+        const recentOperations = this.operations.filter((op) => op.timestamp >= startTime && op.timestamp <= endTime);
+        if (recentOperations.length === 0) {
+            return this.createEmptyMetrics(startTime, endTime);
+        }
+        const hits = recentOperations.filter((op) => op.hit).length;
+        const misses = recentOperations.filter((op) => !op.hit).length;
+        const errors = recentOperations.filter((op) => op.error).length;
+        const latencies = recentOperations
+            .map((op) => op.latency)
+            .sort((a, b) => a - b);
+        const gets = recentOperations.filter((op) => op.type === 'get').length;
+        const sets = recentOperations.filter((op) => op.type === 'set').length;
+        const deletes = recentOperations.filter((op) => op.type === 'delete').length;
+        const clears = recentOperations.filter((op) => op.type === 'clear').length;
+        const layerOperations = {
+            cls: recentOperations.filter((op) => op.layer === 'cls'),
+            memory: recentOperations.filter((op) => op.layer === 'memory'),
+            redis: recentOperations.filter((op) => op.layer === 'redis'),
+        };
+        const layerMetrics = {
+            cls: this.calculateLayerMetrics(layerOperations.cls),
+            memory: this.calculateLayerMetrics(layerOperations.memory),
+            redis: this.calculateLayerMetrics(layerOperations.redis),
+        };
+        return {
+            totalOperations: recentOperations.length,
+            hits,
+            misses,
+            hitRate: recentOperations.length > 0 ? hits / recentOperations.length : 0,
+            avgLatency: this.average(latencies),
+            minLatency: latencies.length > 0 ? latencies[0] : 0,
+            maxLatency: latencies.length > 0 ? latencies[latencies.length - 1] : 0,
+            p95Latency: this.percentile(latencies, 0.95),
+            p99Latency: this.percentile(latencies, 0.99),
+            gets,
+            sets,
+            deletes,
+            clears,
+            totalKeys: this.getUniqueKeyCount(recentOperations),
+            totalSize: this.estimateTotalSize(recentOperations),
+            errors,
+            errorRate: recentOperations.length > 0 ? errors / recentOperations.length : 0,
+            layerMetrics,
+            timeWindow: {
+                start: startTime,
+                end: endTime,
+                duration: timeWindowMs,
+            },
+        };
+    }
+    getSnapshot() {
+        const now = new Date();
+        const oneMinuteAgo = new Date(now.getTime() - 60000);
+        const recentOperations = this.operations.filter((op) => op.timestamp >= oneMinuteAgo);
+        if (recentOperations.length === 0) {
+            return {
+                totalOperations: 0,
+                hits: 0,
+                misses: 0,
+                hitRate: 0,
+                avgLatency: 0,
+                errors: 0,
+                errorRate: 0,
+            };
+        }
+        const hits = recentOperations.filter((op) => op.hit).length;
+        const errors = recentOperations.filter((op) => op.error).length;
+        const latencies = recentOperations.map((op) => op.latency);
+        return {
+            totalOperations: recentOperations.length,
+            hits,
+            misses: recentOperations.length - hits,
+            hitRate: hits / recentOperations.length,
+            avgLatency: this.average(latencies),
+            minLatency: Math.min(...latencies),
+            maxLatency: Math.max(...latencies),
+            errors,
+            errorRate: errors / recentOperations.length,
+        };
+    }
+    getSlowOperations(limit = 10) {
+        return this.operations
+            .filter((op) => op.error === undefined)
+            .sort((a, b) => b.latency - a.latency)
+            .slice(0, limit);
+    }
+    getMostAccessedKeys(limit = 10) {
+        const keyStats = new Map();
+        this.operations.forEach((op) => {
+            if (op.key) {
+                const stats = keyStats.get(op.key) || { count: 0, totalLatency: 0 };
+                stats.count++;
+                stats.totalLatency += op.latency;
+                keyStats.set(op.key, stats);
+            }
+        });
+        return Array.from(keyStats.entries())
+            .map(([key, stats]) => ({
+            key,
+            count: stats.count,
+            avgLatency: stats.totalLatency / stats.count,
+        }))
+            .sort((a, b) => b.count - a.count)
+            .slice(0, limit);
+    }
+    getErrorBreakdown() {
+        const errorStats = new Map();
+        this.operations.forEach((op) => {
+            if (op.error) {
+                const stats = errorStats.get(op.error) || {
+                    count: 0,
+                    lastOccurrence: op.timestamp,
+                };
+                stats.count++;
+                stats.lastOccurrence =
+                    op.timestamp > stats.lastOccurrence
+                        ? op.timestamp
+                        : stats.lastOccurrence;
+                errorStats.set(op.error, stats);
+            }
+        });
+        return Array.from(errorStats.entries())
+            .map(([error, stats]) => ({
+            error,
+            count: stats.count,
+            lastOccurrence: stats.lastOccurrence,
+        }))
+            .sort((a, b) => b.count - a.count);
+    }
+    resetMetrics() {
+        this.operations.length = 0;
+        this.logger.log('Cache metrics reset');
+        this.emit('reset');
+    }
+    exportMetrics(format = 'json') {
+        const metrics = this.getMetrics();
+        if (format === 'prometheus') {
+            return this.toPrometheusFormat(metrics);
+        }
+        return JSON.stringify(metrics, null, 2);
+    }
+    cleanupOldRecords() {
+        const cutoff = new Date(Date.now() - this.maxAge);
+        const initialLength = this.operations.length;
+        for (let i = this.operations.length - 1; i >= 0; i--) {
+            if (this.operations[i].timestamp < cutoff) {
+                this.operations.splice(0, i + 1);
+                break;
+            }
+        }
+        const removed = initialLength - this.operations.length;
+        if (removed > 0) {
+            this.logger.debug(`Cleaned up ${removed} old cache operation records`);
+        }
+    }
+    createEmptyMetrics(start, end) {
+        return {
+            totalOperations: 0,
+            hits: 0,
+            misses: 0,
+            hitRate: 0,
+            avgLatency: 0,
+            minLatency: 0,
+            maxLatency: 0,
+            p95Latency: 0,
+            p99Latency: 0,
+            gets: 0,
+            sets: 0,
+            deletes: 0,
+            clears: 0,
+            totalKeys: 0,
+            totalSize: 0,
+            errors: 0,
+            errorRate: 0,
+            layerMetrics: {
+                cls: { hits: 0, misses: 0, avgLatency: 0 },
+                memory: { hits: 0, misses: 0, avgLatency: 0, size: 0 },
+                redis: { hits: 0, misses: 0, avgLatency: 0 },
+            },
+            timeWindow: {
+                start,
+                end,
+                duration: end.getTime() - start.getTime(),
+            },
+        };
+    }
+    calculateLayerMetrics(operations) {
+        const hits = operations.filter((op) => op.hit).length;
+        const misses = operations.filter((op) => !op.hit).length;
+        const latencies = operations.map((op) => op.latency);
+        return {
+            hits,
+            misses,
+            avgLatency: latencies.length > 0 ? this.average(latencies) : 0,
+            size: operations.length,
+        };
+    }
+    average(numbers) {
+        return numbers.length > 0
+            ? numbers.reduce((sum, num) => sum + num, 0) / numbers.length
+            : 0;
+    }
+    percentile(sortedNumbers, p) {
+        if (sortedNumbers.length === 0)
+            return 0;
+        const index = Math.ceil(sortedNumbers.length * p) - 1;
+        return sortedNumbers[Math.max(0, Math.min(index, sortedNumbers.length - 1))];
+    }
+    getUniqueKeyCount(operations) {
+        const keys = new Set();
+        operations.forEach((op) => {
+            if (op.key)
+                keys.add(op.key);
+        });
+        return keys.size;
+    }
+    estimateTotalSize(operations) {
+        const avgValueSize = 120;
+        return this.getUniqueKeyCount(operations) * avgValueSize;
+    }
+    toPrometheusFormat(metrics) {
+        const labels = {
+            layer: 'cls|memory|redis',
+        };
+        let output = '';
+        output += `# HELP cache_hit_rate Cache hit rate\n`;
+        output += `# TYPE cache_hit_rate gauge\n`;
+        output += `cache_hit_rate ${metrics.hitRate}\n`;
+        output += `# HELP cache_operations_total Total cache operations\n`;
+        output += `# TYPE cache_operations_total counter\n`;
+        output += `cache_operations_total{type="get"} ${metrics.gets}\n`;
+        output += `cache_operations_total{type="set"} ${metrics.sets}\n`;
+        output += `cache_operations_total{type="delete"} ${metrics.deletes}\n`;
+        output += `cache_operations_total{type="clear"} ${metrics.clears}\n`;
+        output += `# HELP cache_latency_ms Cache operation latency\n`;
+        output += `# TYPE cache_latency_ms histogram\n`;
+        output += `cache_latency_ms{quantile="0.5"} ${metrics.avgLatency}\n`;
+        output += `cache_latency_ms{quantile="0.95"} ${metrics.p95Latency}\n`;
+        output += `cache_latency_ms{quantile="0.99"} ${metrics.p99Latency}\n`;
+        Object.entries(metrics.layerMetrics).forEach(([layer, layerMetrics]) => {
+            output += `cache_layer_hits_total{layer="${layer}"} ${layerMetrics.hits}\n`;
+            output += `cache_layer_misses_total{layer="${layer}"} ${layerMetrics.misses}\n`;
+            output += `cache_layer_latency_ms{layer="${layer}"} ${layerMetrics.avgLatency}\n`;
+        });
+        return output;
+    }
+};
+exports.CacheMetricsService = CacheMetricsService;
+exports.CacheMetricsService = CacheMetricsService = CacheMetricsService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [])
+], CacheMetricsService);

package/cache/cache-serialization.service.d.ts

@@ -0,0 +1,29 @@
+export interface CacheSerializationOptions {
+    compress?: boolean;
+    compressThreshold?: number;
+    serializer?: (value: any) => string;
+    deserializer?: (data: string) => any;
+    preserveTypes?: boolean;
+}
+export interface SerializationResult {
+    data: Buffer;
+    compressed: boolean;
+    originalSize: number;
+    serializedSize: number;
+}
+export interface DeserializationResult<T> {
+    data: T;
+    wasCompressed: boolean;
+    wasSerialized: boolean;
+}
+export declare class CacheSerializationService {
+    private readonly logger;
+    serialize<T>(value: T, options?: CacheSerializationOptions): Promise<SerializationResult>;
+    deserialize<T>(buffer: Buffer, options?: CacheSerializationOptions): Promise<DeserializationResult<T>>;
+    getSerializationStats(value: any, options?: CacheSerializationOptions): any;
+    validateSerializedData(buffer: Buffer): boolean;
+    getOptimalOptions(value: any): CacheSerializationOptions;
+    private preserveTypeSerialization;
+    private preserveTypeDeserialization;
+    private hasComplexTypes;
+}

package/cache/cache-serialization.service.js

@@ -0,0 +1,217 @@
+"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 __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 CacheSerializationService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheSerializationService = void 0;
+const common_1 = require("@nestjs/common");
+const zlib_1 = require("zlib");
+const util_1 = require("util");
+const gzipAsync = (0, util_1.promisify)(zlib_1.gzip);
+const gunzipAsync = (0, util_1.promisify)(zlib_1.gunzip);
+let CacheSerializationService = CacheSerializationService_1 = class CacheSerializationService {
+    constructor() {
+        this.logger = new common_1.Logger(CacheSerializationService_1.name);
+    }
+    serialize(value_1) {
+        return __awaiter(this, arguments, void 0, function* (value, options = {}) {
+            const { compress = false, compressThreshold = 1024, serializer, preserveTypes = true, } = options;
+            try {
+                let serializedData;
+                let wasSerialized = false;
+                if (serializer) {
+                    serializedData = serializer(value);
+                    wasSerialized = true;
+                }
+                else {
+                    serializedData = preserveTypes
+                        ? this.preserveTypeSerialization(value)
+                        : JSON.stringify(value);
+                    wasSerialized = true;
+                }
+                const originalSize = Buffer.byteLength(serializedData, 'utf8');
+                let data;
+                let wasCompressed = false;
+                if (compress && originalSize >= compressThreshold) {
+                    try {
+                        data = yield gzipAsync(Buffer.from(serializedData, 'utf8'));
+                        wasCompressed = true;
+                    }
+                    catch (error) {
+                        this.logger.warn('Compression failed, using uncompressed data:', error);
+                        data = Buffer.from(serializedData, 'utf8');
+                    }
+                }
+                else {
+                    data = Buffer.from(serializedData, 'utf8');
+                }
+                return {
+                    data,
+                    compressed: wasCompressed,
+                    originalSize,
+                    serializedSize: data.length,
+                };
+            }
+            catch (error) {
+                this.logger.error('Serialization failed:', error);
+                throw new Error(`Failed to serialize cache value: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        });
+    }
+    deserialize(buffer_1) {
+        return __awaiter(this, arguments, void 0, function* (buffer, options = {}) {
+            const { deserializer, preserveTypes = true } = options;
+            try {
+                let dataString;
+                let wasCompressed = false;
+                if (buffer.length >= 2 && buffer[0] === 0x1f && buffer[1] === 0x8b) {
+                    dataString = (yield gunzipAsync(buffer)).toString('utf8');
+                    wasCompressed = true;
+                }
+                else {
+                    dataString = buffer.toString('utf8');
+                }
+                let data;
+                let wasSerialized = true;
+                if (deserializer) {
+                    data = deserializer(dataString);
+                }
+                else {
+                    data = preserveTypes
+                        ? this.preserveTypeDeserialization(dataString)
+                        : JSON.parse(dataString);
+                }
+                return {
+                    data,
+                    wasCompressed,
+                    wasSerialized,
+                };
+            }
+            catch (error) {
+                this.logger.error('Deserialization failed:', error);
+                throw new Error(`Failed to deserialize cache value: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        });
+    }
+    getSerializationStats(value, options = {}) {
+        const valueStr = JSON.stringify(value);
+        const valueSize = Buffer.byteLength(valueStr, 'utf8');
+        return {
+            originalSize: valueSize,
+            estimatedCompressedSize: Math.floor(valueSize * 0.6),
+            recommendedCompression: valueSize >= (options.compressThreshold || 1024),
+            hasComplexTypes: this.hasComplexTypes(value),
+        };
+    }
+    validateSerializedData(buffer) {
+        if (!Buffer.isBuffer(buffer)) {
+            return false;
+        }
+        if (buffer.length === 0) {
+            return false;
+        }
+        if (!(buffer.length >= 2 && buffer[0] === 0x1f && buffer[1] === 0x8b)) {
+            try {
+                buffer.toString('utf8');
+                return true;
+            }
+            catch (_a) {
+                return false;
+            }
+        }
+        return true;
+    }
+    getOptimalOptions(value) {
+        const stats = this.getSerializationStats(value);
+        const options = {};
+        if (stats.recommendedCompression) {
+            options.compress = true;
+            options.compressThreshold = 1024;
+        }
+        if (stats.hasComplexTypes) {
+            options.preserveTypes = true;
+        }
+        return options;
+    }
+    preserveTypeSerialization(value) {
+        return JSON.stringify(value, (key, val) => {
+            if (val instanceof Date) {
+                return { __type: 'Date', value: val.toISOString() };
+            }
+            if (val instanceof RegExp) {
+                return { __type: 'RegExp', value: val.source, flags: val.flags };
+            }
+            if (val instanceof Set) {
+                return { __type: 'Set', value: Array.from(val) };
+            }
+            if (val instanceof Map) {
+                return { __type: 'Map', value: Array.from(val.entries()) };
+            }
+            if (typeof val === 'bigint') {
+                return { __type: 'BigInt', value: val.toString() };
+            }
+            if (Buffer.isBuffer(val)) {
+                return { __type: 'Buffer', value: Array.from(val) };
+            }
+            return val;
+        });
+    }
+    preserveTypeDeserialization(dataString) {
+        return JSON.parse(dataString, (key, val) => {
+            if (val && typeof val === 'object' && val.__type) {
+                switch (val.__type) {
+                    case 'Date':
+                        return new Date(val.value);
+                    case 'RegExp':
+                        return new RegExp(val.value, val.flags);
+                    case 'Set':
+                        return new Set(val.value);
+                    case 'Map':
+                        return new Map(val.value);
+                    case 'BigInt':
+                        return BigInt(val.value);
+                    case 'Buffer':
+                        return Buffer.from(val.value);
+                    default:
+                        return val;
+                }
+            }
+            return val;
+        });
+    }
+    hasComplexTypes(value) {
+        if (value instanceof Date ||
+            value instanceof RegExp ||
+            value instanceof Set ||
+            value instanceof Map) {
+            return true;
+        }
+        if (Buffer.isBuffer(value) || typeof value === 'bigint') {
+            return true;
+        }
+        if (Array.isArray(value)) {
+            return value.some((item) => this.hasComplexTypes(item));
+        }
+        if (value && typeof value === 'object') {
+            return Object.values(value).some((item) => this.hasComplexTypes(item));
+        }
+        return false;
+    }
+};
+exports.CacheSerializationService = CacheSerializationService;
+exports.CacheSerializationService = CacheSerializationService = CacheSerializationService_1 = __decorate([
+    (0, common_1.Injectable)()
+], CacheSerializationService);

package/cache/cache.health.d.ts

@@ -0,0 +1,35 @@
+import { CacheService } from './cache.service';
+export interface CacheHealthResult {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    layers: {
+        cls: {
+            available: boolean;
+            latency?: number;
+            error?: string;
+        };
+        memory: {
+            available: boolean;
+            latency?: number;
+            size?: number;
+            error?: string;
+        };
+        redis: {
+            available: boolean;
+            latency?: number;
+            error?: string;
+        };
+    };
+    timestamp: Date;
+    overallLatency: number;
+}
+export declare class CacheHealthChecker {
+    private readonly cacheService;
+    private readonly logger;
+    constructor(cacheService: CacheService);
+    checkHealth(): Promise<CacheHealthResult>;
+    getDetailedStats(): Promise<any>;
+    private checkClsHealth;
+    private checkMemoryHealth;
+    private checkRedisHealth;
+    private generateRecommendations;
+}