ts-prorm-orm 1.1.0

package/dist/query-optimizers/query-optimizer.js

@@ -0,0 +1,278 @@
+"use strict";
+/**
+ * Query Optimizer - Main entry point that combines all optimization features
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryOptimizer = void 0;
+exports.createQueryOptimizer = createQueryOptimizer;
+const query_hints_1 = require("./query-hints");
+const explain_plans_1 = require("./explain-plans");
+const slow_query_logger_1 = require("./slow-query-logger");
+const batch_optimizer_1 = require("./batch-optimizer");
+const prepared_statement_cache_1 = require("./prepared-statement-cache");
+/**
+ * Main query optimizer class that combines all optimization features
+ */
+class QueryOptimizer {
+    constructor(dialect, options) {
+        this.dialect = dialect;
+        this.options = {
+            enableHints: options?.enableHints ?? true,
+            enableExplain: options?.enableExplain ?? process.env.NODE_ENV === 'development',
+            enableSlowQueryLog: options?.enableSlowQueryLog ?? true,
+            enablePreparedStatementCache: options?.enablePreparedStatementCache ?? true,
+            enableQueryResultCache: options?.enableQueryResultCache ?? true,
+            enableBatchOptimization: options?.enableBatchOptimization ?? true,
+            slowQueryOptions: {
+                threshold: 1000,
+                ...options?.slowQueryOptions,
+            },
+            preparedStatementCacheOptions: {
+                maxSize: 500,
+                ...options?.preparedStatementCacheOptions,
+            },
+            queryResultCacheOptions: {
+                maxSize: 100,
+                ttl: 60000,
+                ...options?.queryResultCacheOptions,
+            },
+            batchOptions: {
+                chunkSize: 1000,
+                useTransaction: true,
+                ...options?.batchOptions,
+            },
+            explainOptions: {
+                ...options?.explainOptions,
+            },
+            logging: options?.logging,
+        };
+        this.initializeComponents();
+    }
+    /**
+     * Initialize all optimization components
+     */
+    initializeComponents() {
+        if (this.options.enableHints) {
+            this.queryHintManager = new query_hints_1.QueryHintManager(this.dialect);
+        }
+        if (this.options.enableExplain) {
+            this.explainPlanGenerator = new explain_plans_1.ExplainPlanGenerator(this.dialect, this.options.explainOptions);
+        }
+        if (this.options.enableSlowQueryLog) {
+            this.slowQueryLogger = new slow_query_logger_1.SlowQueryLogger(this.options.slowQueryOptions);
+        }
+        if (this.options.enablePreparedStatementCache) {
+            this.preparedStatementCache = new prepared_statement_cache_1.PreparedStatementCache(this.dialect, this.options.preparedStatementCacheOptions);
+        }
+        if (this.options.enableQueryResultCache) {
+            this.queryResultCache = new prepared_statement_cache_1.QueryResultCache(this.options.queryResultCacheOptions);
+        }
+        if (this.options.enableBatchOptimization) {
+            this.batchOptimizer = new batch_optimizer_1.BatchQueryOptimizer(this.dialect, this.options.batchOptions);
+        }
+    }
+    /**
+     * Get the query hint manager
+     */
+    getHintManager() {
+        return this.queryHintManager;
+    }
+    /**
+     * Get the explain plan generator
+     */
+    getExplainGenerator() {
+        return this.explainPlanGenerator;
+    }
+    /**
+     * Get the slow query logger
+     */
+    getSlowQueryLogger() {
+        return this.slowQueryLogger;
+    }
+    /**
+     * Get the prepared statement cache
+     */
+    getPreparedStatementCache() {
+        return this.preparedStatementCache;
+    }
+    /**
+     * Get the query result cache
+     */
+    getQueryResultCache() {
+        return this.queryResultCache;
+    }
+    /**
+     * Get the batch optimizer
+     */
+    getBatchOptimizer() {
+        return this.batchOptimizer;
+    }
+    /**
+     * Apply query hints to a SQL statement
+     */
+    applyHints(sql, hints) {
+        if (!this.queryHintManager) {
+            return sql;
+        }
+        return this.queryHintManager.applyHints(sql, hints);
+    }
+    /**
+     * Execute an optimized query with caching support
+     */
+    async executeQuery(sql, options) {
+        const startTime = Date.now();
+        // Apply hints if provided
+        let finalSql = sql;
+        if (options?.hint && this.queryHintManager) {
+            finalSql = this.queryHintManager.applyHints(sql, options.hint);
+        }
+        // Check query result cache
+        if (options?.useCache && this.queryResultCache && !options.params) {
+            const cached = this.queryResultCache.get(finalSql);
+            if (cached !== undefined) {
+                return { result: cached, fromCache: true, duration: Date.now() - startTime };
+            }
+        }
+        // Check prepared statement cache
+        let cacheKey;
+        if (options?.usePreparedStatement && this.preparedStatementCache) {
+            const cached = this.preparedStatementCache.get(finalSql, options.params);
+            if (cached) {
+                // Use cached prepared statement
+                const execStart = Date.now();
+                const result = await this.dialect.query(finalSql, { raw: true });
+                this.preparedStatementCache.recordExecution(cached.key, Date.now() - execStart);
+                // Log slow query
+                if (!options?.skipSlowLog && this.slowQueryLogger) {
+                    this.slowQueryLogger.logQuery({
+                        sql: finalSql,
+                        params: options.params,
+                        duration: Date.now() - startTime,
+                        dialect: this.dialect.name,
+                    });
+                }
+                return { result, fromCache: false, duration: Date.now() - startTime };
+            }
+        }
+        // Execute query
+        const result = await this.dialect.query(finalSql, { raw: true });
+        const duration = Date.now() - startTime;
+        // Cache result if enabled
+        if (options?.useCache && this.queryResultCache) {
+            this.queryResultCache.set(finalSql, options.params ?? [], result);
+        }
+        // Track statement usage if enabled. Note: `PreparedStatementCache` does not
+        // hold a real driver-level prepared-statement handle (see its class doc) -
+        // `compiled` here is just a lightweight, genuinely reusable descriptor of
+        // the statement shape (SQL + bound parameter count).
+        if (options?.usePreparedStatement && this.preparedStatementCache) {
+            this.preparedStatementCache.set(finalSql, { sql: finalSql, paramCount: options.params?.length ?? 0 }, options.params);
+        }
+        // Log slow query
+        if (!options?.skipSlowLog && this.slowQueryLogger) {
+            this.slowQueryLogger.logQuery({
+                sql: finalSql,
+                params: options?.params,
+                duration,
+                dialect: this.dialect.name,
+            });
+        }
+        return { result, fromCache: false, duration };
+    }
+    /**
+     * Explain a query
+     */
+    async explainQuery(sql, options) {
+        if (!this.explainPlanGenerator) {
+            throw new Error('Explain plans are not enabled');
+        }
+        return this.explainPlanGenerator.explain(sql, options);
+    }
+    /**
+     * Analyze a query for optimization opportunities
+     */
+    async analyzeQuery(sql, options) {
+        if (!this.explainPlanGenerator) {
+            throw new Error('Explain plans are not enabled');
+        }
+        return this.explainPlanGenerator.analyzeQuery(sql, options);
+    }
+    /**
+     * Perform batch insert with optimization
+     */
+    async batchInsert(tableName, records, options) {
+        if (!this.batchOptimizer) {
+            throw new Error('Batch optimization is not enabled');
+        }
+        return this.batchOptimizer.optimizeBatchInsert(tableName, records, options);
+    }
+    /**
+     * Perform batch update with optimization
+     */
+    async batchUpdate(tableName, records, identifierColumn, options) {
+        if (!this.batchOptimizer) {
+            throw new Error('Batch optimization is not enabled');
+        }
+        return this.batchOptimizer.optimizeBatchUpdate(tableName, records, identifierColumn, options);
+    }
+    /**
+     * Perform batch delete with optimization
+     */
+    async batchDelete(tableName, identifiers, identifierColumn, options) {
+        if (!this.batchOptimizer) {
+            throw new Error('Batch optimization is not enabled');
+        }
+        return this.batchOptimizer.optimizeBatchDelete(tableName, identifiers, identifierColumn, options);
+    }
+    /**
+     * Get optimization statistics
+     */
+    getStats() {
+        return {
+            slowQuery: this.slowQueryLogger?.getStatistics(),
+            preparedStatementCache: this.preparedStatementCache?.getStats(),
+            queryResultCache: this.queryResultCache?.getStats(),
+        };
+    }
+    /**
+     * Clear all caches
+     */
+    clearCaches() {
+        this.preparedStatementCache?.clear();
+        this.queryResultCache?.clear();
+        this.slowQueryLogger?.clear();
+    }
+    /**
+     * Prune expired cache entries
+     */
+    pruneCaches() {
+        this.preparedStatementCache?.prune();
+    }
+    /**
+     * Invalidate query result cache for a specific table
+     */
+    invalidateTableCache(tableName) {
+        const resultCacheInvalidated = this.queryResultCache?.invalidateTable(tableName) ?? 0;
+        const preparedStatementCacheInvalidated = this.preparedStatementCache?.invalidateTable(tableName) ?? 0;
+        return resultCacheInvalidated + preparedStatementCacheInvalidated;
+    }
+    /**
+     * Log a message
+     */
+    log(message, level = 'info') {
+        if (this.options.logging) {
+            this.options.logging(message, level);
+        }
+    }
+}
+exports.QueryOptimizer = QueryOptimizer;
+/**
+ * Create a query optimizer instance
+ */
+function createQueryOptimizer(dialect, options) {
+    return new QueryOptimizer(dialect, options);
+}
+exports.default = {
+    QueryOptimizer,
+    createQueryOptimizer,
+};

package/dist/query-optimizers/slow-query-logger.js

@@ -0,0 +1,271 @@
+"use strict";
+/**
+ * Slow Query Logging
+ * Provides functionality to log and analyze slow database queries
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SlowQueryLogger = void 0;
+exports.createSlowQueryLogger = createSlowQueryLogger;
+const events_1 = require("events");
+/**
+ * Slow query logger
+ */
+class SlowQueryLogger extends events_1.EventEmitter {
+    constructor(options) {
+        super();
+        this.logAllQueries = false;
+        this.logParams = false;
+        this.maxEntries = 1000;
+        this.includeStackTrace = false;
+        this.logs = [];
+        this.alertThreshold = 10;
+        this.alertWindow = 60000; // 1 minute
+        this.queryTimestamps = [];
+        this.threshold = options.threshold || SlowQueryLogger.DEFAULT_THRESHOLD;
+        this.logAllQueries = options.logAllQueries || false;
+        this.logParams = options.logParams || false;
+        this.maxEntries = options.maxEntries || 1000;
+        this.onSlowQuery = options.onSlowQuery;
+        this.onAlert = options.onAlert;
+        this.includeStackTrace = options.includeStackTrace || false;
+        this.logger = options.logger;
+        if (options.alertThreshold !== undefined) {
+            this.alertThreshold = options.alertThreshold;
+        }
+        if (options.alertWindow !== undefined) {
+            this.alertWindow = options.alertWindow;
+        }
+    }
+    /**
+     * Set the slow query threshold
+     */
+    setThreshold(threshold) {
+        this.threshold = threshold;
+    }
+    /**
+     * Get the current threshold
+     */
+    getThreshold() {
+        return this.threshold;
+    }
+    /**
+     * Enable logging of all queries (not just slow ones)
+     */
+    setLogAllQueries(logAll) {
+        this.logAllQueries = logAll;
+    }
+    /**
+     * Log a query execution
+     */
+    logQuery(options) {
+        const entry = {
+            id: this.generateId(),
+            sql: options.sql,
+            params: this.logParams ? options.params : undefined,
+            duration: options.duration,
+            timestamp: new Date(),
+            dialect: options.dialect,
+            inTransaction: options.inTransaction || false,
+            connection: options.connection,
+            error: options.error,
+            queryType: options.queryType,
+            rowCount: options.rowCount,
+        };
+        if (this.includeStackTrace) {
+            entry.stackTrace = new Error().stack;
+        }
+        // Determine if this should be logged
+        const shouldLog = this.logAllQueries || options.duration >= this.threshold;
+        if (shouldLog) {
+            this.addLogEntry(entry);
+            // Log the query
+            this.logEntry(entry);
+            // Emit events
+            this.emit('query', entry);
+            if (options.duration >= this.threshold) {
+                this.emit('slowQuery', entry);
+                if (this.onSlowQuery) {
+                    this.onSlowQuery(entry);
+                }
+                // Check alert threshold
+                this.checkAlertThreshold();
+            }
+        }
+        return shouldLog ? entry : null;
+    }
+    /**
+     * Add a log entry to the internal log storage
+     */
+    addLogEntry(entry) {
+        this.logs.push(entry);
+        // Maintain max entries limit
+        if (this.logs.length > this.maxEntries) {
+            this.logs.shift();
+        }
+        // Track query timestamps for alerting
+        if (entry.duration >= this.threshold) {
+            this.queryTimestamps.push(Date.now());
+        }
+    }
+    /**
+     * Log the entry using the configured logger
+     */
+    logEntry(entry) {
+        const isSlow = entry.duration >= this.threshold;
+        const level = isSlow ? 'warn' : 'debug';
+        const meta = {
+            duration: `${entry.duration}ms`,
+            dialect: entry.dialect,
+            queryType: entry.queryType,
+            rowCount: entry.rowCount,
+            inTransaction: entry.inTransaction,
+        };
+        const message = isSlow
+            ? `[SLOW] Query exceeded threshold (${this.threshold}ms): ${entry.sql}`
+            : entry.sql;
+        if (this.logger) {
+            this.logger(message, meta);
+        }
+        else {
+            // Default console logging
+            if (isSlow) {
+                console.warn(`[SLOW QUERY] ${message}`, meta);
+            }
+            else {
+                console.log(`[QUERY] ${message}`, meta);
+            }
+        }
+    }
+    /**
+     * Check if alert threshold has been exceeded
+     */
+    checkAlertThreshold() {
+        const now = Date.now();
+        const windowStart = now - this.alertWindow;
+        // Remove timestamps outside the window
+        this.queryTimestamps = this.queryTimestamps.filter((ts) => ts >= windowStart);
+        if (this.queryTimestamps.length >= this.alertThreshold) {
+            // Get all slow queries in the window
+            const alertEntries = this.logs.filter((entry) => entry.timestamp.getTime() >= windowStart && entry.duration >= this.threshold);
+            this.emit('alert', alertEntries);
+            if (this.onAlert) {
+                this.onAlert(alertEntries);
+            }
+        }
+    }
+    /**
+     * Get all log entries
+     */
+    getLogs() {
+        return [...this.logs];
+    }
+    /**
+     * Get slow query entries only
+     */
+    getSlowQueries() {
+        return this.logs.filter((entry) => entry.duration >= this.threshold);
+    }
+    /**
+     * Get query statistics
+     */
+    getStatistics() {
+        const slowQueries = this.getSlowQueries();
+        const totalQueries = this.logs.length;
+        if (totalQueries === 0) {
+            return {
+                totalQueries: 0,
+                slowQueries: 0,
+                averageDuration: 0,
+                maxDuration: 0,
+                minDuration: 0,
+                p50Duration: 0,
+                p95Duration: 0,
+                p99Duration: 0,
+            };
+        }
+        const durations = this.logs.map((e) => e.duration).sort((a, b) => a - b);
+        return {
+            totalQueries,
+            slowQueries: slowQueries.length,
+            averageDuration: durations.reduce((a, b) => a + b, 0) / totalQueries,
+            maxDuration: durations[durations.length - 1],
+            minDuration: durations[0],
+            p50Duration: this.percentile(durations, 50),
+            p95Duration: this.percentile(durations, 95),
+            p99Duration: this.percentile(durations, 99),
+        };
+    }
+    /**
+     * Calculate percentile from sorted array
+     */
+    percentile(sortedArray, p) {
+        if (sortedArray.length === 0)
+            return 0;
+        const index = Math.ceil((p / 100) * sortedArray.length) - 1;
+        return sortedArray[Math.max(0, index)];
+    }
+    /**
+     * Clear all log entries
+     */
+    clear() {
+        this.logs = [];
+        this.queryTimestamps = [];
+    }
+    /**
+     * Generate a unique ID for log entries
+     */
+    generateId() {
+        return `sq_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+    /**
+     * Export logs to a file-compatible format
+     */
+    exportLogs() {
+        return JSON.stringify(this.logs, null, 2);
+    }
+    /**
+     * Get queries by type
+     */
+    getQueriesByType(type) {
+        return this.logs.filter((entry) => entry.queryType?.toUpperCase() === type.toUpperCase());
+    }
+    /**
+     * Get queries on a specific table
+     */
+    getQueriesOnTable(tableName) {
+        const regex = new RegExp(`\\b${tableName}\\b`, 'i');
+        return this.logs.filter((entry) => regex.test(entry.sql));
+    }
+    /**
+     * Find similar queries (group by SQL pattern)
+     */
+    findSimilarQueries(sql) {
+        // Normalize SQL by replacing literal values with placeholders
+        const normalizedSql = this.normalizeSql(sql);
+        const normalized = this.normalizeSql(normalizedSql);
+        return this.logs.filter((entry) => this.normalizeSql(entry.sql) === normalized);
+    }
+    /**
+     * Normalize SQL for comparison
+     */
+    normalizeSql(sql) {
+        return sql
+            .replace(/'[^']*'/g, '?')
+            .replace(/"[^"]*"/g, '?')
+            .replace(/\d+/g, '?')
+            .replace(/\s+/g, ' ')
+            .trim();
+    }
+}
+exports.SlowQueryLogger = SlowQueryLogger;
+SlowQueryLogger.DEFAULT_THRESHOLD = 1000; // 1 second
+/**
+ * Create a slow query logger instance
+ */
+function createSlowQueryLogger(options) {
+    return new SlowQueryLogger(options);
+}
+exports.default = {
+    SlowQueryLogger,
+    createSlowQueryLogger,
+};