noormme 1.0.0 → 1.0.2

package/dist/esm/performance/query-optimizer.d.ts

@@ -0,0 +1,134 @@
+import { Kysely } from '../kysely';
+import { Logger } from '../logging/logger.js';
+import { SchemaInfo } from '../types';
+export interface QueryOptimizationOptions {
+    enableQueryCache: boolean;
+    enableIndexRecommendations: boolean;
+    enableQueryRewriting: boolean;
+    slowQueryThreshold: number;
+    cacheSize: number;
+    maxCacheAge: number;
+}
+export interface QueryOptimizationResult {
+    originalQuery: string;
+    optimizedQuery: string;
+    optimizationType: 'index_hint' | 'query_rewrite' | 'cache_hit' | 'no_optimization';
+    executionTime: number;
+    improvement: number;
+    suggestions: string[];
+    result?: any;
+}
+export interface IndexRecommendation {
+    table: string;
+    columns: string[];
+    type: 'btree' | 'hash' | 'unique';
+    reason: string;
+    estimatedImprovement: number;
+    priority: 'low' | 'medium' | 'high';
+}
+/**
+ * Refactored query optimizer using focused services
+ */
+export declare class QueryOptimizer {
+    private db;
+    private cacheService;
+    private metricsCollector;
+    private options;
+    private logger;
+    private schemaInfo;
+    constructor(db: Kysely<any>, schemaInfo: SchemaInfo, options?: Partial<QueryOptimizationOptions>, logger?: Logger);
+    /**
+     * Optimize and execute a query
+     */
+    optimizeQuery<T>(query: string, params?: any[], context?: {
+        table?: string;
+        operation?: string;
+    }): Promise<QueryOptimizationResult & {
+        result: T;
+    }>;
+    /**
+     * Get index recommendations
+     */
+    getIndexRecommendations(): Promise<IndexRecommendation[]>;
+    /**
+     * Get query performance statistics
+     */
+    getQueryStats(): {
+        cache: import("./services/cache-service").CacheStats;
+        indexRecommendations: number;
+        totalQueries: number;
+        averageExecutionTime: number;
+        slowQueries: number;
+        errorRate: number;
+        warningCount: {
+            [key: string]: number;
+        };
+        topSlowQueries: Array<{
+            query: string;
+            averageTime: number;
+            count: number;
+        }>;
+        queryPatterns: Array<{
+            pattern: string;
+            frequency: number;
+            averageTime: number;
+        }>;
+    };
+    /**
+     * Clear query cache
+     */
+    clearCache(): void;
+    /**
+     * Clear metrics
+     */
+    clearMetrics(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): import("./services/cache-service").CacheStats;
+    /**
+     * Get performance warnings
+     */
+    getPerformanceWarnings(): import("./services/metrics-collector").PerformanceWarning[];
+    /**
+     * Shutdown optimizer
+     */
+    shutdown(): void;
+    /**
+     * Analyze query for optimization opportunities
+     */
+    private analyzeQuery;
+    /**
+     * Optimize SELECT queries
+     */
+    private optimizeSelectQuery;
+    /**
+     * Optimize complex queries (joins, aggregates)
+     */
+    private optimizeComplexQuery;
+    /**
+     * Analyze query for index recommendations
+     */
+    private analyzeQueryForIndexes;
+    /**
+     * Deduplicate index recommendations
+     */
+    private deduplicateRecommendations;
+    /**
+     * Generate optimization suggestions
+     */
+    private generateSuggestions;
+    /**
+     * Execute a query with error handling
+     * Note: This creates a proper SQL query with parameters
+     */
+    private executeQuery;
+    /**
+     * Check if column has an index
+     */
+    private hasIndexOnColumn;
+}
+/**
+ * Factory function to create query optimizer
+ */
+export declare function createQueryOptimizer(db: Kysely<any>, schemaInfo: SchemaInfo, options?: Partial<QueryOptimizationOptions>, logger?: Logger): QueryOptimizer;

package/dist/esm/performance/query-optimizer.js

@@ -0,0 +1,387 @@
+/// <reference types="./query-optimizer.d.ts" />
+import { Logger } from '../logging/logger.js';
+import { QueryParser } from './utils/query-parser';
+import { QueryCacheService } from './services/cache-service';
+import { MetricsCollector } from './services/metrics-collector';
+import { sql } from '../raw-builder/sql';
+/**
+ * Refactored query optimizer using focused services
+ */
+export class QueryOptimizer {
+    db;
+    cacheService;
+    metricsCollector;
+    options;
+    logger;
+    schemaInfo;
+    constructor(db, schemaInfo, options = {}, logger) {
+        this.db = db;
+        this.schemaInfo = schemaInfo;
+        this.logger = logger || new Logger('QueryOptimizer');
+        this.options = {
+            enableQueryCache: true,
+            enableIndexRecommendations: true,
+            enableQueryRewriting: true,
+            slowQueryThreshold: 1000,
+            cacheSize: 1000,
+            maxCacheAge: 300000,
+            ...options
+        };
+        // Initialize services
+        this.cacheService = new QueryCacheService({
+            maxSize: this.options.cacheSize,
+            defaultTtl: this.options.maxCacheAge,
+            enableMetrics: true
+        }, this.logger);
+        this.metricsCollector = new MetricsCollector({
+            enabled: true,
+            slowQueryThreshold: this.options.slowQueryThreshold,
+            nPlusOneDetection: true,
+            missingIndexDetection: this.options.enableIndexRecommendations,
+            largeResultSetThreshold: 1000
+        }, this.logger);
+    }
+    /**
+     * Optimize and execute a query
+     */
+    async optimizeQuery(query, params = [], context) {
+        const startTime = performance.now();
+        try {
+            // Check cache first
+            if (this.options.enableQueryCache) {
+                const cachedResult = this.cacheService.getCachedQuery(query, params);
+                if (cachedResult) {
+                    const executionTime = performance.now() - startTime;
+                    return {
+                        originalQuery: query,
+                        optimizedQuery: query,
+                        optimizationType: 'cache_hit',
+                        executionTime,
+                        improvement: 100,
+                        suggestions: ['Query served from cache'],
+                        result: cachedResult
+                    };
+                }
+            }
+            // Parse and analyze query
+            const parsedQuery = QueryParser.parseQuery(query);
+            const optimization = await this.analyzeQuery(parsedQuery, query, params);
+            const optimizedQuery = optimization.optimizedQuery || query;
+            // Execute the query
+            const result = await this.executeQuery(optimizedQuery, params);
+            const executionTime = performance.now() - startTime;
+            // Cache the result if appropriate
+            if (this.options.enableQueryCache &&
+                QueryParser.shouldCache(query, executionTime)) {
+                this.cacheService.cacheQuery(query, params, result);
+            }
+            // Record metrics
+            this.metricsCollector.recordQuery(query, executionTime, {
+                table: context?.table,
+                operation: context?.operation,
+                resultCount: Array.isArray(result) ? result.length : 1
+            });
+            // Generate suggestions
+            const suggestions = this.generateSuggestions(parsedQuery, executionTime, context);
+            return {
+                originalQuery: query,
+                optimizedQuery,
+                optimizationType: optimization.type,
+                executionTime,
+                improvement: optimization.improvement,
+                suggestions,
+                result
+            };
+        }
+        catch (error) {
+            const executionTime = performance.now() - startTime;
+            // Record error metrics
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.metricsCollector.recordQuery(query, executionTime, {
+                table: context?.table,
+                operation: context?.operation,
+                error: errorMessage
+            });
+            this.logger.error(`Query optimization failed: ${errorMessage}`, {
+                query,
+                executionTime
+            });
+            throw error;
+        }
+    }
+    /**
+     * Get index recommendations
+     */
+    async getIndexRecommendations() {
+        if (!this.options.enableIndexRecommendations) {
+            return [];
+        }
+        const slowQueries = this.metricsCollector.getSlowQueries();
+        const recommendations = [];
+        for (const queryInfo of slowQueries) {
+            const parsedQuery = QueryParser.parseQuery(queryInfo.query);
+            const queryRecommendations = this.analyzeQueryForIndexes(parsedQuery, queryInfo.query);
+            recommendations.push(...queryRecommendations);
+        }
+        return this.deduplicateRecommendations(recommendations);
+    }
+    /**
+     * Get query performance statistics
+     */
+    getQueryStats() {
+        const metricsStats = this.metricsCollector.getPerformanceStats();
+        const cacheStats = this.cacheService.getStats();
+        return {
+            ...metricsStats,
+            cache: cacheStats,
+            indexRecommendations: 0 // Would be populated by recommendations
+        };
+    }
+    /**
+     * Clear query cache
+     */
+    clearCache() {
+        this.cacheService.clear();
+    }
+    /**
+     * Clear metrics
+     */
+    clearMetrics() {
+        this.metricsCollector.clear();
+    }
+    /**
+     * Get cache statistics
+     */
+    getCacheStats() {
+        return this.cacheService.getStats();
+    }
+    /**
+     * Get performance warnings
+     */
+    getPerformanceWarnings() {
+        return this.metricsCollector.getRecentWarnings();
+    }
+    /**
+     * Shutdown optimizer
+     */
+    shutdown() {
+        this.cacheService.shutdown();
+        this.metricsCollector.shutdown();
+    }
+    /**
+     * Analyze query for optimization opportunities
+     */
+    async analyzeQuery(parsedQuery, originalQuery, params) {
+        let optimizedQuery = originalQuery;
+        let improvement = 0;
+        let type = 'no_optimization';
+        // Apply query-specific optimizations
+        if (parsedQuery.type === 'SELECT') {
+            const selectOptimization = this.optimizeSelectQuery(parsedQuery, originalQuery);
+            if (selectOptimization.improvement > 0) {
+                optimizedQuery = selectOptimization.optimizedQuery;
+                improvement = selectOptimization.improvement;
+                type = 'query_rewrite';
+            }
+        }
+        if (parsedQuery.isComplex) {
+            const complexOptimization = this.optimizeComplexQuery(parsedQuery, originalQuery);
+            if (complexOptimization.improvement > improvement) {
+                optimizedQuery = complexOptimization.optimizedQuery;
+                improvement = complexOptimization.improvement;
+                type = 'query_rewrite';
+            }
+        }
+        return {
+            optimizedQuery,
+            type,
+            improvement
+        };
+    }
+    /**
+     * Optimize SELECT queries
+     */
+    optimizeSelectQuery(parsedQuery, originalQuery) {
+        let optimizedQuery = originalQuery;
+        let improvement = 0;
+        // Add LIMIT if missing and query could return many rows
+        if (!parsedQuery.hasLimit && QueryParser.couldReturnManyRows(originalQuery)) {
+            optimizedQuery = `${originalQuery} LIMIT 1000`;
+            improvement = 10;
+        }
+        // Optimize ORDER BY with LIMIT
+        if (parsedQuery.hasLimit && parsedQuery.orderByColumns.length > 0) {
+            const orderByColumn = parsedQuery.orderByColumns[0];
+            const table = parsedQuery.tables[0];
+            if (table && this.hasIndexOnColumn(table, orderByColumn)) {
+                improvement = Math.max(improvement, 20);
+            }
+        }
+        return {
+            optimizedQuery,
+            improvement
+        };
+    }
+    /**
+     * Optimize complex queries (joins, aggregates)
+     */
+    optimizeComplexQuery(parsedQuery, originalQuery) {
+        let optimizedQuery = originalQuery;
+        let improvement = 0;
+        // Check for missing indexes on join columns
+        for (const { table, column } of parsedQuery.joinColumns) {
+            if (!this.hasIndexOnColumn(table, column)) {
+                improvement = Math.max(improvement, 15);
+            }
+        }
+        // Check for missing indexes on WHERE columns
+        for (const column of parsedQuery.whereColumns) {
+            const table = parsedQuery.tables[0];
+            if (table && !this.hasIndexOnColumn(table, column)) {
+                improvement = Math.max(improvement, 20);
+            }
+        }
+        // Check for missing indexes on GROUP BY columns
+        if (parsedQuery.hasAggregates && parsedQuery.groupByColumns.length > 0) {
+            const table = parsedQuery.tables[0];
+            if (table && parsedQuery.groupByColumns.every(col => this.hasIndexOnColumn(table, col))) {
+                improvement = Math.max(improvement, 25);
+            }
+        }
+        return {
+            optimizedQuery,
+            improvement
+        };
+    }
+    /**
+     * Analyze query for index recommendations
+     */
+    analyzeQueryForIndexes(parsedQuery, originalQuery) {
+        const recommendations = [];
+        const table = parsedQuery.tables[0];
+        if (!table) {
+            return recommendations;
+        }
+        // Analyze WHERE clauses
+        for (const column of parsedQuery.whereColumns) {
+            if (!this.hasIndexOnColumn(table, column)) {
+                recommendations.push({
+                    table,
+                    columns: [column],
+                    type: 'btree',
+                    reason: `WHERE clause on ${column}`,
+                    estimatedImprovement: 20,
+                    priority: 'medium'
+                });
+            }
+        }
+        // Analyze JOIN columns
+        for (const { table: joinTable, column } of parsedQuery.joinColumns) {
+            if (!this.hasIndexOnColumn(joinTable, column)) {
+                recommendations.push({
+                    table: joinTable,
+                    columns: [column],
+                    type: 'btree',
+                    reason: `JOIN condition on ${column}`,
+                    estimatedImprovement: 30,
+                    priority: 'high'
+                });
+            }
+        }
+        // Analyze ORDER BY columns
+        for (const column of parsedQuery.orderByColumns) {
+            if (!this.hasIndexOnColumn(table, column)) {
+                recommendations.push({
+                    table,
+                    columns: [column],
+                    type: 'btree',
+                    reason: `ORDER BY clause on ${column}`,
+                    estimatedImprovement: 15,
+                    priority: 'medium'
+                });
+            }
+        }
+        return recommendations;
+    }
+    /**
+     * Deduplicate index recommendations
+     */
+    deduplicateRecommendations(recommendations) {
+        const unique = new Map();
+        for (const rec of recommendations) {
+            const key = `${rec.table}:${rec.columns.join(',')}`;
+            if (!unique.has(key) || unique.get(key).priority === 'low') {
+                unique.set(key, rec);
+            }
+        }
+        return Array.from(unique.values()).sort((a, b) => {
+            const priorityOrder = { high: 3, medium: 2, low: 1 };
+            return priorityOrder[b.priority] - priorityOrder[a.priority];
+        });
+    }
+    /**
+     * Generate optimization suggestions
+     */
+    generateSuggestions(parsedQuery, executionTime, context) {
+        const suggestions = [];
+        if (executionTime > this.options.slowQueryThreshold) {
+            suggestions.push(`Query took ${executionTime.toFixed(2)}ms - consider adding indexes`);
+        }
+        if (parsedQuery.type === 'SELECT' && !parsedQuery.hasLimit) {
+            suggestions.push('Consider adding LIMIT clause to prevent large result sets');
+        }
+        if (parsedQuery.joinColumns.length > 0) {
+            for (const { table, column } of parsedQuery.joinColumns) {
+                if (!this.hasIndexOnColumn(table, column)) {
+                    suggestions.push(`Consider adding index on ${table}.${column} for join optimization`);
+                }
+            }
+        }
+        if (parsedQuery.hasAggregates && parsedQuery.groupByColumns.length > 0) {
+            suggestions.push('Consider adding composite indexes for GROUP BY columns');
+        }
+        return suggestions;
+    }
+    /**
+     * Execute a query with error handling
+     * Note: This creates a proper SQL query with parameters
+     */
+    async executeQuery(query, params) {
+        try {
+            // Split query by '?' placeholders and create template string array
+            const parts = query.split('?');
+            const templateStrings = Object.assign([...parts], { raw: [...parts] });
+            // Create SQL query using template tag syntax
+            const sqlQuery = sql(templateStrings, ...params);
+            // Compile the query first to match the expected interface
+            const compiledQuery = sqlQuery.compile(this.db);
+            const result = await this.db.executeQuery(compiledQuery);
+            return result.rows;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.error(`Query execution failed: ${errorMessage}`, { query, params });
+            throw error;
+        }
+    }
+    /**
+     * Check if column has an index
+     */
+    hasIndexOnColumn(table, column) {
+        const tableInfo = this.schemaInfo.tables.find(t => t.name === table);
+        if (!tableInfo)
+            return false;
+        // Check if column is primary key
+        const columnInfo = tableInfo.columns.find(col => col.name === column);
+        if (columnInfo?.isPrimaryKey)
+            return true;
+        // Check if column has an index
+        return tableInfo.indexes.some(idx => idx.columns.includes(column));
+    }
+}
+/**
+ * Factory function to create query optimizer
+ */
+export function createQueryOptimizer(db, schemaInfo, options, logger) {
+    return new QueryOptimizer(db, schemaInfo, options, logger);
+}

package/dist/esm/performance/services/cache-service.d.ts

@@ -0,0 +1,177 @@
+import { Logger } from '../../logging/logger.js';
+export interface CacheEntry<T = any> {
+    key: string;
+    value: T;
+    timestamp: number;
+    ttl: number;
+    hitCount: number;
+    size: number;
+}
+export interface CacheConfig {
+    maxSize: number;
+    defaultTtl: number;
+    cleanupInterval: number;
+    enableCompression: boolean;
+    enableMetrics: boolean;
+}
+export interface CacheStats {
+    size: number;
+    maxSize: number;
+    hitCount: number;
+    missCount: number;
+    hitRate: number;
+    totalSize: number;
+    evictions: number;
+    lastCleanup: Date;
+}
+export interface CacheMetrics {
+    operations: {
+        get: number;
+        set: number;
+        delete: number;
+        clear: number;
+    };
+    performance: {
+        averageGetTime: number;
+        averageSetTime: number;
+        slowestOperation: number;
+    };
+    memory: {
+        totalSize: number;
+        averageEntrySize: number;
+        largestEntry: number;
+    };
+}
+/**
+ * Generic cache service with TTL, size limits, and metrics
+ */
+export declare class CacheService<T = any> {
+    private cache;
+    private config;
+    private stats;
+    private metrics;
+    private cleanupTimer?;
+    protected logger: Logger;
+    constructor(config?: Partial<CacheConfig>, logger?: Logger);
+    /**
+     * Get a value from cache
+     */
+    get(key: string): T | null;
+    /**
+     * Set a value in cache
+     */
+    set(key: string, value: T, ttl?: number): boolean;
+    /**
+     * Delete a value from cache
+     */
+    delete(key: string): boolean;
+    /**
+     * Check if key exists in cache
+     */
+    has(key: string): boolean;
+    /**
+     * Clear all entries from cache
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Get detailed metrics
+     */
+    getMetrics(): CacheMetrics;
+    /**
+     * Get cache size
+     */
+    size(): number;
+    /**
+     * Get all cache keys
+     */
+    keys(): string[];
+    /**
+     * Get cache entries (for debugging)
+     */
+    entries(): Array<{
+        key: string;
+        entry: CacheEntry<T>;
+    }>;
+    /**
+     * Warm cache with multiple entries
+     */
+    warm(entries: Array<{
+        key: string;
+        value: T;
+        ttl?: number;
+    }>): number;
+    /**
+     * Get cache health status
+     */
+    getHealth(): {
+        status: 'healthy' | 'warning' | 'critical';
+        issues: string[];
+        recommendations: string[];
+    };
+    /**
+     * Shutdown cache service
+     */
+    shutdown(): void;
+    /**
+     * Check if cache entry is expired
+     */
+    private isExpired;
+    /**
+     * Calculate size of a value (rough estimation)
+     */
+    private calculateSize;
+    /**
+     * Evict entries when cache is full
+     */
+    private evictEntries;
+    /**
+     * Update cache statistics
+     */
+    private updateStats;
+    /**
+     * Update hit rate
+     */
+    private updateHitRate;
+    /**
+     * Update performance metrics
+     */
+    private updatePerformanceMetrics;
+    /**
+     * Start cleanup timer
+     */
+    private startCleanupTimer;
+    /**
+     * Cleanup expired entries
+     */
+    private cleanup;
+}
+/**
+ * Factory function to create cache service
+ */
+export declare function createCacheService<T = any>(config?: Partial<CacheConfig>, logger?: Logger): CacheService<T>;
+/**
+ * Specialized query cache service
+ */
+export declare class QueryCacheService extends CacheService<any> {
+    constructor(config?: Partial<CacheConfig>, logger?: Logger);
+    /**
+     * Cache query result with automatic key generation
+     */
+    cacheQuery(query: string, params: any[], result: any, ttl?: number): boolean;
+    /**
+     * Get cached query result
+     */
+    getCachedQuery(query: string, params: any[]): any | null;
+    /**
+     * Generate cache key for query
+     */
+    private generateQueryKey;
+    /**
+     * Invalidate cache entries for a specific table
+     */
+    invalidateTable(table: string): number;
+}