noormme 1.0.0 → 1.0.2

package/dist/esm/performance/services/cache-service.js

@@ -0,0 +1,410 @@
+/// <reference types="./cache-service.d.ts" />
+import { Logger } from '../../logging/logger.js';
+/**
+ * Generic cache service with TTL, size limits, and metrics
+ */
+export class CacheService {
+    cache = new Map();
+    config;
+    stats;
+    metrics;
+    cleanupTimer;
+    logger;
+    constructor(config = {}, logger) {
+        this.logger = logger || new Logger('CacheService');
+        this.config = {
+            maxSize: 1000,
+            defaultTtl: 300000, // 5 minutes
+            cleanupInterval: 60000, // 1 minute
+            enableCompression: false,
+            enableMetrics: true,
+            ...config
+        };
+        this.stats = {
+            size: 0,
+            maxSize: this.config.maxSize,
+            hitCount: 0,
+            missCount: 0,
+            hitRate: 0,
+            totalSize: 0,
+            evictions: 0,
+            lastCleanup: new Date()
+        };
+        this.metrics = {
+            operations: {
+                get: 0,
+                set: 0,
+                delete: 0,
+                clear: 0
+            },
+            performance: {
+                averageGetTime: 0,
+                averageSetTime: 0,
+                slowestOperation: 0
+            },
+            memory: {
+                totalSize: 0,
+                averageEntrySize: 0,
+                largestEntry: 0
+            }
+        };
+        this.startCleanupTimer();
+    }
+    /**
+     * Get a value from cache
+     */
+    get(key) {
+        const startTime = performance.now();
+        try {
+            this.metrics.operations.get++;
+            const entry = this.cache.get(key);
+            if (!entry) {
+                this.stats.missCount++;
+                this.updateHitRate();
+                return null;
+            }
+            // Check if entry has expired
+            if (this.isExpired(entry)) {
+                this.cache.delete(key);
+                this.stats.missCount++;
+                this.updateHitRate();
+                this.updateStats();
+                return null;
+            }
+            // Update hit count and last access
+            entry.hitCount++;
+            this.stats.hitCount++;
+            this.updateHitRate();
+            const duration = performance.now() - startTime;
+            this.updatePerformanceMetrics('get', duration);
+            return entry.value;
+        }
+        catch (error) {
+            this.logger.error(`Cache get error for key ${key}:`, error);
+            return null;
+        }
+    }
+    /**
+     * Set a value in cache
+     */
+    set(key, value, ttl) {
+        const startTime = performance.now();
+        try {
+            this.metrics.operations.set++;
+            const entrySize = this.calculateSize(value);
+            const entryTtl = ttl || this.config.defaultTtl;
+            // Check if we need to evict entries
+            if (this.cache.size >= this.config.maxSize) {
+                this.evictEntries();
+            }
+            const entry = {
+                key,
+                value,
+                timestamp: Date.now(),
+                ttl: entryTtl,
+                hitCount: 0,
+                size: entrySize
+            };
+            this.cache.set(key, entry);
+            this.updateStats();
+            const duration = performance.now() - startTime;
+            this.updatePerformanceMetrics('set', duration);
+            return true;
+        }
+        catch (error) {
+            this.logger.error(`Cache set error for key ${key}:`, error);
+            return false;
+        }
+    }
+    /**
+     * Delete a value from cache
+     */
+    delete(key) {
+        try {
+            this.metrics.operations.delete++;
+            const deleted = this.cache.delete(key);
+            if (deleted) {
+                this.updateStats();
+            }
+            return deleted;
+        }
+        catch (error) {
+            this.logger.error(`Cache delete error for key ${key}:`, error);
+            return false;
+        }
+    }
+    /**
+     * Check if key exists in cache
+     */
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return false;
+        if (this.isExpired(entry)) {
+            this.cache.delete(key);
+            this.updateStats();
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Clear all entries from cache
+     */
+    clear() {
+        try {
+            this.metrics.operations.clear++;
+            this.cache.clear();
+            this.updateStats();
+            this.logger.info('Cache cleared');
+        }
+        catch (error) {
+            this.logger.error('Cache clear error:', error);
+        }
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Get detailed metrics
+     */
+    getMetrics() {
+        return { ...this.metrics };
+    }
+    /**
+     * Get cache size
+     */
+    size() {
+        return this.cache.size;
+    }
+    /**
+     * Get all cache keys
+     */
+    keys() {
+        return Array.from(this.cache.keys());
+    }
+    /**
+     * Get cache entries (for debugging)
+     */
+    entries() {
+        return Array.from(this.cache.entries()).map(([key, entry]) => ({ key, entry }));
+    }
+    /**
+     * Warm cache with multiple entries
+     */
+    warm(entries) {
+        let warmed = 0;
+        for (const { key, value, ttl } of entries) {
+            if (this.set(key, value, ttl)) {
+                warmed++;
+            }
+        }
+        this.logger.info(`Warmed cache with ${warmed}/${entries.length} entries`);
+        return warmed;
+    }
+    /**
+     * Get cache health status
+     */
+    getHealth() {
+        const issues = [];
+        const recommendations = [];
+        // Check hit rate
+        if (this.stats.hitRate < 0.5) {
+            issues.push(`Low hit rate: ${(this.stats.hitRate * 100).toFixed(1)}%`);
+            recommendations.push('Consider increasing TTL or cache size');
+        }
+        // Check memory usage
+        if (this.stats.totalSize > 100 * 1024 * 1024) { // 100MB
+            issues.push(`High memory usage: ${(this.stats.totalSize / 1024 / 1024).toFixed(1)}MB`);
+            recommendations.push('Consider reducing cache size or enabling compression');
+        }
+        // Check eviction rate
+        const evictionRate = this.stats.evictions / Math.max(this.stats.hitCount + this.stats.missCount, 1);
+        if (evictionRate > 0.1) {
+            issues.push(`High eviction rate: ${(evictionRate * 100).toFixed(1)}%`);
+            recommendations.push('Consider increasing cache size');
+        }
+        let status = 'healthy';
+        if (issues.length > 0) {
+            status = issues.some(issue => issue.includes('critical')) ? 'critical' : 'warning';
+        }
+        return { status, issues, recommendations };
+    }
+    /**
+     * Shutdown cache service
+     */
+    shutdown() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+        }
+        this.clear();
+        this.logger.info('Cache service shutdown');
+    }
+    /**
+     * Check if cache entry is expired
+     */
+    isExpired(entry) {
+        return Date.now() - entry.timestamp > entry.ttl;
+    }
+    /**
+     * Calculate size of a value (rough estimation)
+     */
+    calculateSize(value) {
+        try {
+            return JSON.stringify(value).length * 2; // Rough estimate in bytes
+        }
+        catch {
+            return 1024; // Default size if serialization fails
+        }
+    }
+    /**
+     * Evict entries when cache is full
+     */
+    evictEntries() {
+        const entries = Array.from(this.cache.entries());
+        // Sort by hit count and timestamp (LRU with hit count consideration)
+        entries.sort((a, b) => {
+            const [, entryA] = a;
+            const [, entryB] = b;
+            // Prefer entries with fewer hits
+            if (entryA.hitCount !== entryB.hitCount) {
+                return entryA.hitCount - entryB.hitCount;
+            }
+            // If hit counts are equal, prefer older entries
+            return entryA.timestamp - entryB.timestamp;
+        });
+        // Remove oldest/lowest hit count entries
+        const toRemove = Math.ceil(entries.length * 0.1); // Remove 10% of entries
+        for (let i = 0; i < toRemove && i < entries.length; i++) {
+            const [key] = entries[i];
+            this.cache.delete(key);
+            this.stats.evictions++;
+        }
+    }
+    /**
+     * Update cache statistics
+     */
+    updateStats() {
+        this.stats.size = this.cache.size;
+        let totalSize = 0;
+        let largestEntry = 0;
+        for (const entry of this.cache.values()) {
+            totalSize += entry.size;
+            largestEntry = Math.max(largestEntry, entry.size);
+        }
+        this.stats.totalSize = totalSize;
+        this.metrics.memory.totalSize = totalSize;
+        this.metrics.memory.largestEntry = largestEntry;
+        this.metrics.memory.averageEntrySize = this.cache.size > 0 ? totalSize / this.cache.size : 0;
+    }
+    /**
+     * Update hit rate
+     */
+    updateHitRate() {
+        const total = this.stats.hitCount + this.stats.missCount;
+        this.stats.hitRate = total > 0 ? this.stats.hitCount / total : 0;
+    }
+    /**
+     * Update performance metrics
+     */
+    updatePerformanceMetrics(operation, duration) {
+        if (!this.config.enableMetrics)
+            return;
+        this.metrics.performance.slowestOperation = Math.max(this.metrics.performance.slowestOperation, duration);
+        if (operation === 'get') {
+            const totalGets = this.metrics.operations.get;
+            this.metrics.performance.averageGetTime =
+                (this.metrics.performance.averageGetTime * (totalGets - 1) + duration) / totalGets;
+        }
+        else if (operation === 'set') {
+            const totalSets = this.metrics.operations.set;
+            this.metrics.performance.averageSetTime =
+                (this.metrics.performance.averageSetTime * (totalSets - 1) + duration) / totalSets;
+        }
+    }
+    /**
+     * Start cleanup timer
+     */
+    startCleanupTimer() {
+        this.cleanupTimer = setInterval(() => {
+            this.cleanup();
+        }, this.config.cleanupInterval);
+    }
+    /**
+     * Cleanup expired entries
+     */
+    cleanup() {
+        const now = Date.now();
+        let cleaned = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (now - entry.timestamp > entry.ttl) {
+                this.cache.delete(key);
+                cleaned++;
+            }
+        }
+        if (cleaned > 0) {
+            this.stats.lastCleanup = new Date();
+            this.updateStats();
+            this.logger.debug(`Cleaned up ${cleaned} expired cache entries`);
+        }
+    }
+}
+/**
+ * Factory function to create cache service
+ */
+export function createCacheService(config, logger) {
+    return new CacheService(config, logger);
+}
+/**
+ * Specialized query cache service
+ */
+export class QueryCacheService extends CacheService {
+    constructor(config, logger) {
+        super({
+            maxSize: 1000,
+            defaultTtl: 300000, // 5 minutes
+            cleanupInterval: 60000, // 1 minute
+            enableMetrics: true,
+            ...config
+        }, logger);
+    }
+    /**
+     * Cache query result with automatic key generation
+     */
+    cacheQuery(query, params, result, ttl) {
+        const key = this.generateQueryKey(query, params);
+        return this.set(key, result, ttl);
+    }
+    /**
+     * Get cached query result
+     */
+    getCachedQuery(query, params) {
+        const key = this.generateQueryKey(query, params);
+        return this.get(key);
+    }
+    /**
+     * Generate cache key for query
+     */
+    generateQueryKey(query, params) {
+        const normalizedQuery = query.replace(/\s+/g, ' ').trim();
+        const paramsKey = params.map(p => String(p)).join('|');
+        return `query:${normalizedQuery}:${paramsKey}`;
+    }
+    /**
+     * Invalidate cache entries for a specific table
+     */
+    invalidateTable(table) {
+        let invalidated = 0;
+        for (const key of this.keys()) {
+            if (key.includes(`FROM ${table}`) || key.includes(`JOIN ${table}`)) {
+                if (this.delete(key)) {
+                    invalidated++;
+                }
+            }
+        }
+        this.logger?.info(`Invalidated ${invalidated} cache entries for table ${table}`);
+        return invalidated;
+    }
+}

package/dist/esm/performance/services/connection-factory.d.ts

@@ -0,0 +1,198 @@
+import { NOORMME } from '../../noormme';
+import { NOORMConfig } from '../../types';
+import { Logger } from '../../logging/logger.js';
+export interface ConnectionConfig extends NOORMConfig {
+    id?: string;
+    maxRetries?: number;
+    retryDelay?: number;
+    validationTimeout?: number;
+}
+export interface PooledConnection {
+    id: string;
+    db: NOORMME;
+    createdAt: Date;
+    lastUsed: Date;
+    isActive: boolean;
+    inUse: boolean;
+    config: ConnectionConfig;
+}
+export interface ConnectionValidationResult {
+    isValid: boolean;
+    error?: string;
+    responseTime?: number;
+}
+export interface ConnectionStats {
+    totalCreated: number;
+    totalDestroyed: number;
+    activeConnections: number;
+    failedCreations: number;
+    averageCreationTime: number;
+    averageValidationTime: number;
+}
+/**
+ * Factory for creating and managing database connections
+ */
+export declare class ConnectionFactory {
+    private connections;
+    private stats;
+    private logger;
+    constructor(logger?: Logger);
+    /**
+     * Create a new database connection
+     */
+    createConnection(config: ConnectionConfig): Promise<PooledConnection>;
+    /**
+     * Validate a connection
+     */
+    validateConnection(connection: PooledConnection): Promise<ConnectionValidationResult>;
+    /**
+     * Get connection by ID
+     */
+    getConnection(id: string): PooledConnection | null;
+    /**
+     * Get all connections
+     */
+    getAllConnections(): PooledConnection[];
+    /**
+     * Get active connections
+     */
+    getActiveConnections(): PooledConnection[];
+    /**
+     * Get idle connections
+     */
+    getIdleConnections(): PooledConnection[];
+    /**
+     * Mark connection as in use
+     */
+    markInUse(connection: PooledConnection): void;
+    /**
+     * Mark connection as idle
+     */
+    markIdle(connection: PooledConnection): void;
+    /**
+     * Destroy a connection
+     */
+    destroyConnection(id: string): Promise<boolean>;
+    /**
+     * Destroy all connections
+     */
+    destroyAllConnections(): Promise<void>;
+    /**
+     * Cleanup inactive connections
+     */
+    cleanupInactiveConnections(maxAge?: number): Promise<number>;
+    /**
+     * Validate all connections
+     */
+    validateAllConnections(): Promise<Array<{
+        id: string;
+        isValid: boolean;
+        error?: string;
+        responseTime?: number;
+    }>>;
+    /**
+     * Get connection statistics
+     */
+    getStats(): ConnectionStats;
+    /**
+     * Get connection health status
+     */
+    getHealthStatus(): Promise<{
+        status: 'healthy' | 'warning' | 'critical';
+        issues: string[];
+        connections: {
+            total: number;
+            active: number;
+            idle: number;
+            inUse: number;
+        };
+    }>;
+    /**
+     * Generate unique connection ID
+     */
+    private generateConnectionId;
+    /**
+     * Update statistics
+     */
+    private updateStats;
+    /**
+     * Update average time for operations
+     */
+    private updateAverageTime;
+}
+/**
+ * Connection pool manager using the factory
+ */
+export declare class ConnectionPoolManager {
+    private factory;
+    private config;
+    private poolConfig;
+    private waitingQueue;
+    private validationTimer?;
+    private isShuttingDown;
+    private logger;
+    constructor(config: ConnectionConfig, poolConfig?: Partial<ConnectionPoolManager['poolConfig']>, logger?: Logger);
+    /**
+     * Initialize the connection pool
+     */
+    initialize(): Promise<void>;
+    /**
+     * Acquire a connection from the pool
+     */
+    acquire(): Promise<PooledConnection>;
+    /**
+     * Release a connection back to the pool
+     */
+    release(connection: PooledConnection): Promise<void>;
+    /**
+     * Execute a function with a pooled connection
+     */
+    withConnection<T>(fn: (db: NOORMME) => Promise<T>): Promise<T>;
+    /**
+     * Get pool statistics
+     */
+    getStats(): {
+        poolSize: number;
+        idleConnections: number;
+        inUseConnections: number;
+        waitingQueue: number;
+        totalCreated: number;
+        totalDestroyed: number;
+        activeConnections: number;
+        failedCreations: number;
+        averageCreationTime: number;
+        averageValidationTime: number;
+    };
+    /**
+     * Shutdown the connection pool
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get idle connection from pool
+     */
+    private getIdleConnection;
+    /**
+     * Wait for a connection to become available
+     */
+    private waitForConnection;
+    /**
+     * Process waiting queue when connections become available
+     */
+    private processWaitingQueue;
+    /**
+     * Start validation timer
+     */
+    private startValidationTimer;
+    /**
+     * Validate all connections in the pool
+     */
+    private validateConnections;
+    /**
+     * Cleanup idle connections that exceed the idle timeout
+     */
+    private cleanupIdleConnections;
+}
+/**
+ * Factory function to create connection pool manager
+ */
+export declare function createConnectionPool(config: ConnectionConfig, poolConfig?: Partial<ConnectionPoolManager['poolConfig']>, logger?: Logger): ConnectionPoolManager;